邹方成
1ab39d2f5a
Some checks failed
Build docker and publish / linux (1.24.5) (push) Failing after 25s
feat(admin): 新增工会管理功能 feat(activity): 添加活动管理相关服务 feat(user): 实现用户道具卡和积分管理 feat(guild): 新增工会成员管理功能 fix: 修复数据库连接配置 fix: 修正jwtoken导入路径 fix: 解决端口冲突问题 style: 统一代码格式和注释风格 style: 更新项目常量命名 docs: 添加项目框架和开发规范文档 docs: 更新接口文档注释 chore: 移除无用代码和文件 chore: 更新Makefile和配置文件 chore: 清理日志文件 test: 添加道具卡测试脚本
82 lines
3.8 KiB
Markdown
82 lines
3.8 KiB
Markdown
# DESIGN: 开发规范文档设计
|
||
|
||
本文档定义了最终 `docs/开发规范.md` 的结构和核心内容，旨在为后续的文档撰写提供清晰的蓝图。
|
||
|
||
## 1. 整体结构
|
||
|
||
最终的开发规范文档将分为以下几个核心章节，每个章节都将包含详细的规则描述和代码示例。
|
||
|
||
```mermaid
|
||
graph TD
|
||
A[开发规范] --\u003e B[1. 概述];
|
||
A --\u003e C[2. 目录与文件结构];
|
||
A --\u003e D[3. 命名规范];
|
||
A --\u003e E[4. API Handler 规范];
|
||
A --\u003e F[5. 数据传输对象 (DTO) 规范];
|
||
A --\u003e G[6. 错误处理规范];
|
||
A --\u003e H[7. 日志记录规范];
|
||
A --\u003e I[8. 注释与文档(Swagger)];
|
||
|
||
subgraph E [4. API Handler 规范]
|
||
E1[4.1 Handler 定义]
|
||
E2[4.2 路由与函数签名]
|
||
E3[4.3 参数绑定与校验]
|
||
E4[4.4 业务逻辑调用]
|
||
E5[4.5 响应处理]
|
||
end
|
||
|
||
subgraph F [5. 数据传输对象 (DTO) 规范]
|
||
F1[5.1 Request/Response 结构体]
|
||
F2[5.2 JSON Tags]
|
||
F3[5.3 Validation Tags]
|
||
end
|
||
```
|
||
|
||
## 2. 核心章节设计
|
||
|
||
### 2.1 概述
|
||
* **目的**：阐明制定此规范的背景和目标。
|
||
* **范围**：明确规范的适用范围（API 层）。
|
||
* **原则**：强调代码清晰、一致、可维护的核心原则。
|
||
|
||
### 2.2 目录与文件结构
|
||
* **规则**：
|
||
* API 功能模块应在 `internal/api/{模块名}` 下创建独立目录。
|
||
* 每个目录包含 `*.go` 文件，每个文件实现一个独立的 API 端点。
|
||
* `{模块名}.go` 文件用于定义 `handler` 结构体和 `New` 初始化函数。
|
||
* **示例**：以 `admin` 模块为例，展示其目录结构。
|
||
|
||
### 2.3 命名规范
|
||
* **规则**：
|
||
* Handler 文件名：使用小写蛇形命名法，如 `login.go`, `admin_create.go`。
|
||
* 请求/响应结构体：使用驼峰式命名，并以 `Request`/`Response` 结尾，如 `loginRequest`, `loginResponse`。
|
||
* Handler 函数：使用驼峰式命名，如 `Login()`, `CreateAdmin()`。
|
||
|
||
### 2.4 API Handler 规范
|
||
* **Handler 定义**：`handler` 结构体应包含 `logger` 和数据库连接（`readDB`, `writeDB`）。
|
||
* **路由与函数签名**：Handler 函数必须返回 `core.HandlerFunc` 类型。
|
||
* **参数绑定与校验**：必须使用 `ctx.ShouldBindJSON()` 进行参数绑定，并结合 `validation` 包进行错误信息格式化。
|
||
* **业务逻辑调用**：通过 `h.readDB` 或 `h.writeDB` 与数据库交互，或调用 `service` 层方法。
|
||
* **响应处理**：成功时使用 `ctx.Payload(res)` 返回数据。
|
||
|
||
### 2.5 数据传输对象 (DTO) 规范
|
||
* **Request/Response 结构体**：每个 API 都应定义独立的请求和响应结构体。
|
||
* **JSON Tags**：所有结构体字段必须包含 `json:"..."` tag。
|
||
* **Validation Tags**：对需要校验的请求字段，必须添加 `binding:"..."` tag。
|
||
|
||
### 2.6 错误处理规范
|
||
* **规则**：必须使用 `ctx.AbortWithError(core.Error(...))` 来中断请求并返回标准格式的错误。
|
||
* **`core.Error` 参数**：需提供 HTTP 状态码、业务错误码 (`code.Code`) 和详细错误信息。
|
||
|
||
### 2.7 日志记录规范
|
||
* **规则**：通过注入的 `h.logger` 实例进行日志记录（虽然在 `admin` 示例中不明显，但这是标准实践）。
|
||
|
||
### 2.8 注释与文档 (Swagger)
|
||
* **规则**：
|
||
* 每个 Handler 函数上方必须有完整的 Swagger 注解，包括 `@Summary`, `@Description`, `@Tags`, `@Param`, `@Success`, `@Failure`, `@Router` 等。
|
||
* 所有 DTO 字段和函数都应有清晰的中文注释。
|
||
|
||
## 3. 数据流与接口契约
|
||
|
||
本文档本身不定义新的数据流或接口，而是规范如何定义它们。其核心思想是：**通过严格的结构体和规范化的错误处理，确保所有 API 的接口契约都是明确和一致的。**
|