项目规范文档 (dsbqj-admin)

本文档旨在概述 dsbqj-admin Go 项目的技术栈、结构、规范和可用命令，为开发者提供统一的指引。

1. 项目概述

这是一个基于 Go 语言和 Gin 框架构建的后台管理系统。项目采用 Monorepo（单一仓库多项目）的组织形式，包含了多个独立运行的服务。

项目名称: dsbqj-admin
Go 版本: 1.24
核心框架: Gin

2. 技术栈

项目采用了一系列成熟的 Go 技术栈，核心技术如下：

Web 框架: github.com/gin-gonic/gin
数据库:
- MongoDB: 使用 go.mongodb.org/mongo-driver 驱动和 github.com/kamva/mgm/v3 ORM。
- MySQL: 使用 github.com/jinzhu/gorm ORM。
缓存: github.com/go-redis/redis
配置: 通过 github.com/joho/godotenv 从 .env 文件加载环境变量。
校验: github.com/go-playground/validator/v10
云服务:
- 阿里云对象存储 (OSS)
- 阿里云短信服务

3. 项目结构

项目遵循了清晰的、按功能划分的目录结构：

.
├── app/                  # 应用核心逻辑
│   ├── api/              # API 接口定义 (HTTP Handler)
│   ├── router/           # 路由注册与配置
│   ├── service/          # 业务逻辑层
│   └── task/             # 后台定时任务
├── config/               # 配置文件 (如 .env.local)
├── main-admin/           # 管理后台服务入口
├── main-point/           # "Point" 服务入口
├── main-subscribe/       # "Subscribe" 服务入口
├── middleware/           # Gin 中间件 (JWT, CORS, Logger)
├── model/                # 数据模型 (区分 Mongo 和 MySQL)
│   ├── mongo/
│   └── mysql/
├── pkg/                  # 可重用的公共包 (工具、日志、配置等)
├── .gitignore
├── go.mod                # Go 模块依赖
├── go.sum
└── build.bat             # 全局构建脚本

4. 编码规范

为了保持代码的一致性和高质量，所有开发者应遵循以下规范：

代码格式化

强制使用 gofmt: 所有提交的代码都必须使用 gofmt 进行格式化。推荐在 IDE 中配置保存时自动格式化。
遵循 Go 社区风格: 编写符合 Go 社区普遍接受的编码风格和模式。

静态检查

使用 go vet: 在提交代码前，运行 go vet ./... 来捕获可疑的构造和潜在错误。
Linter (推荐): 虽然项目中未包含 .golangci.yml，但强烈建议使用 golangci-lint 并配置一套合理的规则，以进行更全面的静态分析。

命名规范

包名: 使用简短、小写且有意义的名称。
变量与函数: 遵循 Go 的驼峰命名法（camelCase 或 PascalCase），并根据其导出状态决定首字母大小写。
接口: 单一方法的接口通常以 -er 结尾（如 Reader, Writer）。

5. 可用命令

项目的主要操作通过根目录及各 main-* 目录下的 build.bat 批处理脚本执行。

build.bat (根目录):
- 用于构建所有或特定的服务。具体用法请查看脚本内容。
main-*/build.bat:
- 用于单独构建和运行对应的服务（admin, point, subscribe）。

运行服务 (示例):

# 进入特定服务的目录
cd main-admin

# 运行构建脚本 (如果脚本支持) 或直接运行 main.go
go run main.go

依赖管理:
- 安装/更新依赖: go mod tidy
- 下载依赖: go mod download

PROJECT_SPEC.md 3.6 KB History Raw