bindbox-game/docs/开发规范/DESIGN_开发规范.md

DESIGN: 开发规范文档设计

本文档定义了最终 docs/开发规范.md 的结构和核心内容，旨在为后续的文档撰写提供清晰的蓝图。

1. 整体结构

最终的开发规范文档将分为以下几个核心章节，每个章节都将包含详细的规则描述和代码示例。

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 的接口契约都是明确和一致的。