Go Zero Development

Go 语言与 go-zero 微服务架构开发技能规范 (Go-Zero Development Skill)

概述 (Overview)

本技能为 AI 代理（AI Coding Agents）及研发工程师在基于 go-zero 框架开发、重构、审查、排查或扩展 Go 语言微服务系统时，提供权威、严密且符合工业级生产标准的架构设计准则与工程红线。

核心设计原则

1. 既有项目代码是第一事实来源 (Primary Source of Truth)：优先遵循并对齐当前项目已建立的代码组织架构与命名约定。
2. 坚持 Go 与 go-zero 惯用模式 (Idiomatic Patterns)：采用地道的 Go 语言语法与 go-zero 官方推荐的分层架构。
3. 严守代码生成边界 (Generated Code Boundaries)：尊重 goctl 的代码生成体系，自动生成的代码一律只读，坚决杜绝手工随意篡改。
4. 拒绝上帝文件 (No God Files)：严格执行单一职责原则，单文件建议 200~300 行，超过 500 行必须重构拆分；一个 API 接口严格对应一个独立 Logic 文件。
5. 最小化非必要变更 (Minimal Changes)：恪守原子化修改原则，坚决不做无关重构与大面积全库格式化。
6. 保持向后兼容 (Backward Compatibility)：除非用户明确要求破坏性变更，否则必须确保对外 API、RPC 与数据结构的向后兼容。
7. 优先复用既有抽象 (Reuse Existing Utilities)：引入新库、工具函数或数据结构前，必须先在代码库中搜索复用既有实现。
8. 强化防御性编程与防吞异常 (Defensive & Zero-Swallow)：严禁使用 _ 静默丢弃有价值的 error，落实结构化并发、Panic 拦截与安全分布式锁。

适用技术栈

• Language: Go (1.20+)
• Core Framework: go-zero, goctl
• Protocols: RESTful HTTP API, gRPC / zrpc, Protocol Buffers (v3), WebSocket
• Data Persistence: GORM / GORM Gen, goctl model (sqlc), MySQL (utf8mb4), MongoDB
• Caching & Locking: Redis (TTL / Lua 分布式锁 / ZSet 延时队列)
• Infra & DevOps: Docker (Multi-stage build & Graceful Shutdown), GitLab CI / GitHub Actions, Kubernetes

1. 通用规则 (General Rules)

1.1 修改前先调研 (Inspect Before Modifying)

在动手修改或创建任何代码之前，必须先按以下顺序执行调研：

1. 审视仓库结构：梳理各微服务的目录划分方式（单体多服务 Monorepo 还是独立服务拆分）。
2. 查阅项目规范：阅读仓库中的 README.md、AGENTS.md、CONTRIBUTING.md 或项目技术文档。
3. 定位契约定义：找到目标接口所在的 .api（HTTP 路由）或 .proto（RPC 协议）定义文件。
4. 梳理代码分层：定位对应的 Handler、Logic、ServiceContext 与 Model 层文件。
5. 参考类似实现：在代码库中检索相似接口或相近业务逻辑的实现范式。
6. 理解依赖与配置：查阅 internal/config 与 internal/svc，确认数据库、缓存及下游 RPC 客户端的注入方式。
7. 确认文件可修改性：辨别目标文件是否由 goctl 自动生成，确定修改源头。

严禁在未理解项目全貌前盲目新建文件或臆造抽象层。

【推荐开发路径】
理解既有模式 → 定位同类实现 → 沿用相同规范 → 实施最小化精准修改

【禁止危险路径】
臆造全新架构 → 强行套用抽象 → 大面积重写既有代码

1.2 现有代码优先级高于通用规则 (Existing Code Has Priority)

当通用的理论最佳实践与当前项目既有的架构习惯产生冲突时：

• 优先遵循当前项目的约定，保持整个代码库风格的高度统一。
• 严禁擅自进行无关代码现代化（如无端将既有项目全库语法重构）。
• 发现架构矛盾或坏味道时：应当在审查总结或说明中主动指出，供人类工程师决策，绝对禁止静默盲改。

示例：如果当前项目在 Logic 层统一使用：

type XxxLogic struct {
    ctx    context.Context
    svcCtx *svc.ServiceContext
}

即使在某些架构理论中更推崇纯接口入参或独立领域服务，也必须严格沿用当前项目的模式编写。

2. 项目发现与调用链路推演 (Project Discovery)

在开发新功能前，必须在脑海中建立完整的调用链视图：

HTTP API 调用链路

Client (HTTP/JSON)
  ↓
API Handler (internal/handler/ - 参数反序列化、基础校验、统一响应)
  ↓
API Logic (internal/logic/ - 业务规则编排、事务、权限、日志)
  ↓
ServiceContext (internal/svc/ - 持有 DB / Redis / RPC Client)
  ↓
Model / Remote RPC (数据存储 / 下游服务)

跨服务 RPC 调用链路

API Logic
  ↓
RPC Client (zrpc client - 接口存根)
  ↓ [gRPC / Protobuf]
RPC Server (internal/server/ - gRPC 服务分发)
  ↓
RPC Logic (internal/logic/ - 服务端核心业务逻辑)
  ↓
Model / Database (持久化层)

典型工程目录布局

.
├── app/                           # 各独立微服务或主业务模块
│   ├── api-service/               # HTTP API 服务
│   │   ├── desc/                  # API 契约定义目录 (按端/业务领域分拆)
│   │   │   ├── user/              # 面向终端用户的契约 (如 user.api)
│   │   │   ├── admin/             # 面向管理后台的契约 (如 admin.api)
│   │   │   ├── common/            # 公共通用接口契约 (如 common.api)
│   │   │   └── api.api            # 根契约文件 (import 汇聚各子契约)
│   │   ├── etc/                   # 运行配置文件 (yaml)
│   │   ├── internal/
│   │   │   ├── config/            # 配置结构体定义
│   │   │   ├── handler/           # HTTP Handler 路由控制器 (goctl 生成，薄控制器)
│   │   │   ├── logic/             # 核心业务逻辑编排 (一个接口对应一个独立 Logic 文件)
│   │   │   ├── svc/               # 服务依赖注入上下文 (ServiceContext)
│   │   │   └── types/             # 请求/响应 DTO 结构体 (goctl 生成)
│   │   └── service.go             # 服务主入口
│   │
│   ├── rpc-service/               # gRPC 微服务
│   │   ├── desc/                  # Protobuf 契约 (*.proto)
│   │   ├── etc/                   # RPC 运行配置
│   │   ├── internal/              # RPC 内部实现 (logic, server, svc)
│   │   └── client/                # 供外部引用的 RPC Client 存根代码
│   │
│   └── worker-service/            # 异步任务/后台巡检服务 (具备 HTTP 控制面契约)
│
├── pkg/                           # 全局通用基础设施与支撑包
│   ├── enums/                     # 领域枚举强类型包 (按领域拆分独立文件)
│   ├── types/                     # 跨服务共享的内存模型与业务实体
│   ├── ctxdata/                   # Context 上下文安全萃取器 (强类型读取)
│   ├── errorx/                    # 统一业务异常与错误码体系
│   └── shard/                     # 分表分库路由工具
│
├── model/                         # 数据访问层 (GORM Gen 或 goctl model)
├── scripts/                       # 自动化构建、代码生成、数据库迁移脚本
├── Dockerfile                     # 容器镜像构建文件
├── Makefile                       # 工程构建、代码生成与测试统一入口
└── go.mod                         # Go 模块依赖定义

3. 全局代码组织与单一职责红线 (No God Files)

🚨 核心架构红线： 严禁在工程中塞入任何庞大的单一文件（上帝文件 God File）！ 系统全部包与层级（API 契约、pkg/enums/、internal/logic/、model/、中间件等）必须 100% 贯彻职责隔离。

3.1 各层级文件拆分标准

1. internal/logic/ 业务用例层：
   • 严格遵循 一个 API 接口 / 用例 = 一个独立 *_logic.go 文件；
   • 严禁把多个接口逻辑合并写入同一个文件中；
   • 单个 Logic 专注于自身用例的参数校验、数据编排、状态机流转与错误包装。
2. desc/ API 契约定义层：
   • 必须按访问端或业务领域分为独立子目录（如 desc/user/, desc/admin/, desc/common/），杜绝数十个接口平铺堆砌在一个巨型 .api 文件中；
   • 根契约 api.api 统一通过相对路径 import 各子契约文件，由 make gen-api 统一驱动编译。
3. pkg/enums/ 领域枚举层：
   • 严禁将全系统所有枚举堆砌进单个 enums.go；
   • 必须按业务领域拆分独立文件（如 order_status.go, user_status.go）；
   • 每个枚举文件必须包含强类型定义、常量组、序列化/反序列化方法及领域专属判定逻辑。
4. pkg/types/ 全局结构体与内存模型层：
   • 必须按数据领域拆分独立文件，禁止所有 Payload 混杂；
   • 结构化数据强制使用强类型结构体承载，严禁使用散装 map[string]any 在跨层业务中传递。
5. model/ 数据持久化层：
   • 严格按表名分为生成代码（*_gen.go 或 *_model_gen.go）与手写业务扩展代码（*_model.go）；
   • 严禁跨表混合编写方法，所有自定义业务查询必须写在对应表的非生成扩展文件中。

3.2 单文件规模与复杂度软约束

• 建议行数：常规业务源文件建议控制在 200 ~ 300 行 之间；
• 重构阈值：当单个文件行数超过 500 行 时，必须主动审视是否违反单一职责原则，并按照领域子实体或功能职责进行拆分重构。

3.3 目录与 Go 包命名分词规范 (Kebab-Case vs. Snake-Case)

• 基础设施与服务层：微服务根目录、Docker 镜像名、部署产物统一采用中划线 kebab-case（如 api-server, order-rpc）；
• Go 源码层：package 名、Go 文件名、子目录必须严格使用小写下划线 snake_case 或小写单单词（如 order_status.go, 包名 wshub），杜绝大小写混合导致跨操作系统构建问题。

4. 领域枚举与强类型转换规范 (pkg/enums/)

4.1 核心三层映射架构

在微服务数据流转中，枚举必须建立严密的三层映射机制：

数据库底层 (MySQL)   Go 业务代码层 (Logic/Model)   外部网络传输 (HTTP/WS JSON)
   tinyint unsigned  ←───────────────→  Go 强类型枚举  ←─────────────────→  英文语义化字符串 (string)
  (1, 2, 3...)                       (StatusActive)                         ("active", "disabled")

1. 数据库底层：强制使用 tinyint unsigned（0 预留为 Unknown，有效业务值从 1 开始，禁止魔法数字）；
2. Go 代码层：统一收敛在 pkg/enums/ 下定义强类型（如 type UserStatus uint8），实现 json.Marshaler / json.Unmarshaler 以及 sql/driver 的 Value / Scan 接口，实现自动无感双向转换；
3. 外部传输 (HTTP / WS JSON)：强制对外呈现为 英文语义化字符串（string），易读且防止枚举数值调整破坏前端解析；
4. 严禁魔法数字与魔法字符串：业务代码中严禁出现 if status == "active" 或 if status == 1，必须使用强类型枚举方法（如 userStatus.IsActive()、orderStatus.CanCancel()）。

5. go-zero API 接口与路由设计规范

5.1 API 定义为单一事实来源 (Source of Truth)

• 所有 HTTP 接口的输入、输出、路径及路由分组由 .api 文件唯一定义；
• 遵循先改契约文件，再通过 goctl / Makefile 生成，最后编写 Logic 业务的开发顺序；
• 严禁手动编辑由 goctl 生成的 Handler / Types / Routes 文件。

5.2 路由分层与路径规范

• 外部公网路由：面向外部终端、前端应用，统一携带版本前缀，如：

  /web-api/v1/{module}/{action}
  

• 内部微服务集群路由：面向微服务间专用调用管道，强制以内部前缀隔离，如：

  /inner-api/v1/{service}/{module}/{action}
  

  • 严禁向外部公网网关暴露 /inner-api/v1/* 路由；
  • 内部接口必须携带 X-Request-ID 等上下文跟踪头。
• 路径命名风格：路由路径中的短语统一使用小写中划线连接 /xxxx-xxxx/（如 /user-group/detail），严禁使用下划线、驼峰或中文拼音。

5.3 基础动作动词规范 (Action Verbs)

5.4 禁止在 URL Path 中传递业务动态 ID (核心红线)

• 查询类接口（GET）：业务标识统一使用 Query 参数传递：
  • ✅ 正确：/web-api/v1/user/detail?user_id=1001
  • ❌ 严禁：/web-api/v1/user/detail/1001 或 /users/{id}
• 变更类接口（POST / PUT / DELETE）：业务 ID 必须包裹在请求 JSON Body 中：
  • ✅ 正确：POST /web-api/v1/user/update，Body 为 {"user_id": "1001", "name": "Alice"}
  • ❌ 严禁：PUT /web-api/v1/user/update/1001

5.5 64 位长整型传输与 JS 精度防丢 (方案: json:",string")

• 精度截断风险：JavaScript 的 Number.MAX_SAFE_INTEGER 为 $2^{53} - 1$（16 位），而雪花 ID 与 64 位大整型为 19~20 位。若直接输出数字给前端，前端解析将发生低位截断（末位变 0）。
• 规范标准：
  • 底层数据库与 Go 结构体统一采用强类型的 int64 / uint64；
  • 在 .api 定义与对外 DTO 结构体中，长整型 ID 字段 Tag 显式追加 ,string（例如 json:"id,string"、json:"user_id,string"）；
  • WebSocket 广播与长连接推送帧中，涉及 64 位整型 ID 必须格式化为字符串输出；
  • 短数值字段约束：普通业务状态码、分页参数（page, page_size, status）严禁盲目加 ,string。

6. 主流统一标准响应与分页规范

为保持对外接口规范的高度通用性与传播友好性，全系统采用主流标准化 REST/JSON 统一响应体系：

6.1 基础标准响应体 (Standard Response Envelope)

所有 HTTP API 响应体均遵循通用标准外层包装：

{
  "code": 0,
  "msg": "ok",
  "data": { ... }
}

• code：业务状态码（整数）。0（或部分标准体系中的 200）代表业务处理成功，非 0 代表特定业务错误；
• msg：人类可读的提示信息（字符串）；
• data：业务载荷数据（对象、数组或 null）。

6.2 通用标准分页响应体 (Pagination Response)

对于所有分页列表查询接口，data 节点内统一包含分页度量元数据与结果集：

{
  "code": 0,
  "msg": "ok",
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 95,
    "total_pages": 5,
    "list": [
      {
        "id": "358866610846437376",
        "name": "示例记录"
      }
    ]
  }
}

通用分页字段标准说明

注：若当前企业既有项目约定使用 Laravel/Django 风格的深度翻页结构（含 current_page, per_page, first_page_url, last_page_url 等导航 URL），严格按既有项目约定为准。新建立项推荐上述轻量通用标准。

6.3 主流统一业务异常与错误码体系 (Mainstream Error Code Standards)

6.3.1 核心设计理念

1. 统一 HTTP 200 响应 + 业务状态码：客户端接口统一返回 HTTP 200 OK（或配合网关协议映射），通过 JSON 响应体内的 code 明确表达业务结果，严禁向前端直接裸抛 HTTP 500；
2. 底层 Error 与对外异常解耦：代码内部使用 Go 标准 error 并通过 %w 向上冒泡记录完整调用栈；面向前端时，通过全局异常处理器统一转译为带有 Code 和安全提示信息的 CodeError；
3. 安全脱敏与防信息泄漏（核心红线）：严禁向客户端暴露任何底层 SQL 报错（如 Duplicate entry ...）、Redis 连接异常、或未捕获的 Panic 堆栈。内部使用 l.Errorf 完整记录排障日志，外部一律转译为友好提示。

6.3.2 业界主流错误码标准体系

团队可根据工程规模，对齐以下业界最通用的两套错误码标准之一：

方案 A：HTTP 语义映射型标准错误码（RESTful-Aligned，中小微服务首选）

以最广为人知的 HTTP 语义状态码作为业务 code 基准，心智负担极低，前后端协作无缝：

方案 B：五位分段式模块化错误码（Alibaba / CNCF 微服务标准，大型服务推荐）

格式规范：[错误来源 1位][模块编号 2位][具体错误 2位]：

• 0：成功
• 10001 ~ 10099（客户端通用错误）：如 10001 参数校验失败，10002 未登录/Token过期，10003 无权限访问，10004 资源不存在，10005 触发限流；
• 20001 ~ 29999（业务逻辑错误）：如 20101 用户账号已被冻结，20201 订单状态流转非法，20202 账户余额或库存不足；
• 30001 ~ 39999（第三方/依赖基础设施错误）：如 30001 数据库执行故障，30002 Redis 缓存故障，30003 远程 RPC 微服务超时。

6.3.3 go-zero 统一异常拦截落地最佳实践

在工程中统一通过 pkg/errorx 封装并在 go-zero 入口注册全局拦截：

// 1. pkg/errorx/error.go - 基础业务异常定义
package errorx

type CodeError struct {
    Code int    `json:"code"`
    Msg  string `json:"msg"`
}

func (e *CodeError) Error() string {
    return e.Msg
}

func NewCodeError(code int, msg string) error {
    return &CodeError{Code: code, Msg: msg}
}

func NewParamError(msg string) error {
    return NewCodeError(422, msg)
}

func NewServerError(msg ...string) error {
    defaultMsg := "服务暂时不可用，请稍后重试"
    if len(msg) > 0 && msg[0] != "" {
        defaultMsg = msg[0]
    }
    return NewCodeError(500, defaultMsg)
}

// 2. 在 main.go 服务启动时注册 go-zero 全局统一错误拦截器
httpx.SetErrorHandlerCtx(func(ctx context.Context, err error) (int, any) {
    switch e := err.(type) {
    case *errorx.CodeError:
        // 预期的业务 CodeError: 直接按统一结构返回
        return http.StatusOK, types.BaseResponse{
            Code: e.Code,
            Msg:  e.Msg,
            Data: nil,
        }
    default:
        // 未捕获的原生系统异常/panic: 记录详细上下文堆栈，对外安全脱敏
        logx.WithContext(ctx).Errorf("[GlobalErrorHandler] unhandled internal error: %+v", err)
        return http.StatusOK, types.BaseResponse{
            Code: 500,
            Msg:  "服务开小差了，请稍后重试",
            Data: nil,
        }
    }
})

// 3. 在 Logic 业务层中标准调用
if req.Name == "" {
    return nil, errorx.NewParamError("用户名不能为空")
}
if user == nil {
    return nil, errorx.NewCodeError(404, "目标用户不存在")
}
if user.Status != enums.UserStatusActive {
    return nil, errorx.NewCodeError(400, "用户账号已被禁用")
}

7. Handler 控制层规范 (Handler Rules)

Handler 必须保持为“薄控制器”（Thin Handler），其唯一职责是协议适配与流程编排：

func CreateUserHandler(svcCtx *svc.ServiceContext) http.HandlerFunc {
    return func(w http.ResponseWriter, r *http.Request) {
        var req types.CreateUserRequest
        // 1. 参数反序列化与基础校验
        if err := httpx.Parse(r, &req); err != nil {
            httpx.ErrorCtx(r.Context(), w, err)
            return
        }

        // 2. 调用 Logic 层
        l := logic.NewCreateUserLogic(r.Context(), svcCtx)
        resp, err := l.CreateUser(&req)
        if err != nil {
            // 3. 统一错误响应处理
            httpx.ErrorCtx(r.Context(), w, err)
            return
        }

        // 4. 成功响应输出
        httpx.OkJsonCtx(r.Context(), w, resp)
    }
}

核心禁令 (红线)

• 绝对禁止在 Handler 中编写业务逻辑代码；
• 绝对禁止在 Handler 中直接查询数据库或操作 Redis；
• 绝对禁止在 Handler 中启动复杂数据库事务。

8. Logic 业务层规范 (Logic Layer)

Logic 层是所有核心业务规则编排的聚合中心。

Logic 方法标准职责

1. 校验业务语义规则（资格前置检查、状态机约束）；
2. 调用持久化 Model 层或下游 RPC 微服务；
3. 执行业务运算与 DTO 转换；
4. 记录带上下文的业务日志（l.Logger.WithContext(l.ctx)）；
5. 包装规范的业务错误并返回响应。

基础设施隔离红线

• 严禁在 Logic 内部动态初始化基础设施连接（禁止在函数内调用 gorm.Open 或连接 Redis）；
• 所有基础设施客户端必须统一通过 l.svcCtx 获取。

9. ServiceContext 与依赖注入规范 (ServiceContext & DI)

type ServiceContext struct {
    Config    config.Config
    UserModel model.UserModel
    Redis     *redis.Redis
    UserRpc   userclient.User
    DB        *gorm.DB
}

• 单例注入：数据库连接池、Redis 客户端、下游 RPC Client 必须在 NewServiceContext 初始化时统一创建，全服务共享；
• 禁止全局可变单例：严禁在包级别定义 var DB *gorm.DB，全局变量会破坏单测 Mock、导致并发竞争与状态污染；
• 通过 Context 消费：在 Logic 中统一通过 l.svcCtx.XXX 引用。

10. goctl 代码生成铁律 (goctl Guidelines)

1. Makefile 封装优先：团队开发中禁止手动裸敲杂乱的 goctl 命令行参数，必须通过 Makefile（如 make gen-api / make gen-model / make gen-rpc）统一触发；
2. 定制模板对齐：使用 ./template 本地定制模板，统一生成代码的文件命名风格（强制小写下划线 snake_case）；
3. 安全 5 步流程：
   • 检查 goctl --version 工具版本；
   • 检查 git status --short 工作区状态；
   • 确认待变更文件范围；
   • 执行 make gen-api / make gen-rpc；
   • 立即执行 git diff 严格审查，确认无误抹除已有手工逻辑。

11. 生成代码边界控制 (Generated Code Boundaries)

由 goctl 自动生成的代码在日常开发中一律视为只读（Read-Only）：

• 典型只读目录/文件：
  • internal/handler/
  • internal/types/types.go
  • internal/server/
  • model/*_gen.go
  • *client/*.go
• 修复原则：生成代码缺失字段或不符预期时，严禁直接在生成文件中打补丁，必须修改源契约（.api / .proto / DDL / 模板）后重新生成。

12. RPC / zrpc 跨服务通信规范

• 严禁跨服务直连异构数据库：若某类数据归属外部服务，必须通过该服务的 RPC 客户端经由接口访问，严禁直连对方数据库查询；
• Proto 契约向前兼容：
  • 新增字段使用全新 tag 编号，严禁修改已有字段语义或复用已删除编号；
  • 废弃字段必须显式声明 reserved：

    message UserDetail {
        reserved 5, 8 to 11;
        string name = 1;
        int64 id = 2;
    }
    

13. 数据库与持久化规范 - MySQL

1. 字符集与 Emoji 原生支持：
   • 数据表字符集必须设为 utf8mb4，排序规则为 utf8mb4_unicode_ci，确保各类 Emoji 表情无损存储；
2. 主键与审计字段标准：
   • 主键统一采用 id bigint unsigned NOT NULL AUTO_INCREMENT PRIMARY KEY；
   • 业务表必须包含标准审计字段：created_at, updated_at, deleted_at；
3. 统一持久化选型：严格使用项目既有抽象（GORM 或 go-zero 内置 sqlc/model），严禁在同一模块混用多套 ORM；
4. 所有表和字段必须具备详尽的中文注释。

14. GORM / GORM Gen 工程规范

14.1 防 SQL 注入与参数化查询

// 正确：参数化查询
db.WithContext(ctx).Where("user_id = ?", userID).First(&user)

// 严禁：字符串拼接防注入漏洞！
db.Where(fmt.Sprintf("user_id = %d", userID)) // 绝对禁止！

14.2 零值陷阱与精准更新

• GORM 使用 Struct 更新时默认会忽略所有零值字段（0, false, ""）：

  // 正确：明确指定 Select 字段或使用 map
  db.Model(&user).Select("Age", "Status").Updates(User{Age: 0, Status: false})
  // 或
  db.Model(&user).Updates(map[string]any{"age": 0, "status": false})
  

14.3 杜绝无条件全表更新或删除

执行 Delete 或 Update 必须确保带有明确的 Where 条件，防范全表被误清空。

14.4 事务标准闭包范式

err := db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
    if err := tx.Create(&order).Error; err != nil {
        return fmt.Errorf("create order: %w", err)
    }
    if err := tx.Model(&inventory).Where("item_id = ? AND stock >= ?", itemID, num).
        UpdateColumn("stock", gorm.Expr("stock - ?", num)).Error; err != nil {
        return fmt.Errorf("deduct stock: %w", err)
    }
    return nil
})

• 严禁将单次读操作包装在事务中（无意义消耗 DB 连接池与锁资源）。

15. 数据库按月分表规范与自愈机制 (Monthly Sharding)

针对日志、流水等单调持续膨胀的大数据量表：

1. 动态表名计算：通过统一工具函数（如 GetOpLogTableName(t time.Time)）按月格式化物理表名（如 operation_logs_202609）；
2. 定时预建 + 写入自愈：
   • 后台 Worker 每月 25 日预建下月物理表；
   • 写入层捕获 MySQL Error 1146 (Table doesn't exist) 异常时，自动触发 DDL 补建表并执行重试自愈；
3. 跨月查询约束：跨月多表查询采用 UNION ALL 拼接，业务层必须强制限制跨度（通常不超过 3 个月）。

16. MongoDB 规范

• 所有 MongoDB 操作首个参数必须显式传递 ctx；
• 正确区分“数据不存在”与“系统故障”，将 mongo.ErrNoDocuments 转化为明确的业务 NotFound 状态。

17. Redis 缓存与分布式锁标准

17.1 命名空间与多环境隔离规范 (Environment-Aware Key Namespace)

为了兼容多套环境共用同一 Redis 实例（如本地联调与测试共用、灰度演练与正式共用）的隔离需求，Redis Key 的命名空间采用分层分段规范：

标准命名格式

{project}:[{env}:]{module}:{object}:{identifier}

常见环境标签 (env) 枚举与场景

• local：开发者本地机器独立调试，与局域网共用 Redis 实例时防止污染共享数据；
• dev：开发联调集成环境；
• test：测试环境 / QA 自动化流水线测试；
• stage / long：预发布长期演练环境、灰度发布节点（Canary）；
• prod：正式生产环境。

核心隔离场景与收益

1. 本地测试共用隔离：多个开发者本地使用同一个内网 Redis 时，增加 local 或开发者标识前缀，杜绝相互覆盖彼此的缓存状态；
2. 灰度发布与正式共用隔离 (Gray / Canary Isolation)：在微服务灰度发布演练或长期预发验证（long / stage）与正式（prod）共用底层 Redis 基础设施时，通过环境标签实现数据无损逻辑隔离，互不踩踏；
3. 独立集群可选省略：在生产环境拥有物理完全隔离的独立 Redis 集群时，环境标签可选省略（保持 {project}:{module}:{object}:{identifier}）；
4. 工程落地最佳实践（配置化注入）：
   • 严禁在业务 Logic 中到处硬编码环境判断（如 if env == "dev"）；
   • 统一在 config.Config 中定义 KeyPrefix: "myproject:dev:"（通过环境变量或对应配置文件覆盖注入）；
   • 在 pkg 或 ServiceContext 中提供统一的 Key 格式化构建函数（如 BuildKey(module, object, id)），业务层透明无感调用。

17.2 TTL（生命周期）约束

• 严禁生成无 TTL 的垃圾缓存：除少数全局发号序列器外，所有业务缓存必须显式设置过期时间（TTL）；
• 在线长连接或会话路由 Key 兜底设置 TTL（由心跳周期性 EXPIRE 续期）。

17.3 安全分布式锁标准实现 (UUID + Lua)

• Lock Key 格式：{project}:[{env}:]lock:{business}:{unique_id}；
  • ⚠️ 环境隔离特别警示：若测试/灰度与共享环境共用 Redis，分布式锁必须携带环境前缀，否则测试环境执行加锁会直接死锁线上业务实体！
• 加锁规则：必须生成随机 UUID 作为 Value，并附带明确的超时 TTL（防死锁）；
• 解锁规则：必须通过 Lua 脚本原子性校验持有者 UUID 后方可删除，绝对禁止直接使用裸 DEL 导致误删他人持有的锁：

  -- 安全释放锁 Lua 脚本
  if redis.call("get", KEYS[1]) == ARGV[1] then
      return redis.call("del", KEYS[1])
  else
      return 0
  end
  

18. Go 语言错误处理与防吞异常工程红线 (Zero Blank Identifier for Error)

🚨 核心工程红线： 在全系统所有生产代码中（除 *_test.go 外），一律严禁使用空标识符 _ 静默忽略 error 或具有业务语义的有意义返回值！

18.1 五大场景标准化处置准则

18.2 典型代码对比与规范范式

// ❌ 严禁写法：静默忽略数据库更新错误与转换异常
_ = l.svcCtx.OrderModel.UpdateStatus(l.ctx, orderID, status)
startTime, _ = time.ParseInLocation("2006-01-02 15:04:05", req.StartTime, time.Local)
_, _ = l.svcCtx.InnerAPIClient.SyncStatus(l.ctx, &req)

// ✅ 标准写法 1 (数据转换与主流程校验):
startTime, err := time.ParseInLocation("2006-01-02 15:04:05", req.StartTime, time.Local)
if err != nil {
    l.Errorf("[OrderList] parse start_time failed: time=%s, err=%v", req.StartTime, err)
    return nil, errorx.NewParamError("开始时间格式非法")
}

// ✅ 标准写法 2 (核心存储更新安全阻断):
if err := l.svcCtx.OrderModel.UpdateStatus(l.ctx, orderID, status); err != nil {
    l.Errorf("[CloseOrder] update order status failed: order_id=%d, err=%v", orderID, err)
    return nil, errorx.NewServerError("更新订单状态失败")
}

// ✅ 标准写法 3 (旁路调用与网络推流显式留痕):
if _, err := l.svcCtx.InnerAPIClient.SyncStatus(l.ctx, &req); err != nil {
    l.Errorf("[InnerAPI] sync status failed: order_id=%d, err=%v", orderID, err)
}
if count, err := l.svcCtx.WsRouter.PushToTarget(ctx, targetID, payload); err != nil {
    l.Errorf("[Push] push msg failed: target_id=%d, err=%v", targetID, err)
} else if count == 0 {
    l.Debugf("[Push] target is offline: target_id=%d", targetID)
}

• 跨层传递错误必须使用 fmt.Errorf("...: %w", err) 包装；
• 业务层与 Logic 层中禁止主动调用 panic()。

19. Context 上下文传递与强类型萃取规范 (pkg/ctxdata)

1. 显式第一参数传递：所有涉及网络 I/O、RPC 调用、数据库操作的方法，必须将 ctx context.Context 作为方法的第一个参数；
2. 严禁上下文断流：在请求处理链路中，严禁无故使用 context.Background() 替代上游传递的 r.Context() 或 l.ctx，否则链路追踪 TraceID 与超时取消彻底失效；
3. 强类型上下文萃取器 (pkg/ctxdata)：
   • 严禁在业务 Logic 中直接手写 ctx.Value("user_id").(string) 裸类型断言（类型不匹配或 key 缺失会直接触发 panic 崩溃）；
   • 统一在 pkg/ctxdata 中封装类型安全的方法：

     package ctxdata
     
     func GetUserID(ctx context.Context) (int64, bool) {
         val, ok := ctx.Value(CtxKeyUserID).(int64)
         return val, ok
     }
     
     func GetTenantID(ctx context.Context) (int64, bool) {
         val, ok := ctx.Value(CtxKeyTenantID).(int64)
         return val, ok
     }
     

4. 网关安全与头注入校验：
   • 外部网关（API Gateway）鉴权通过后注入私有请求头（如 X-User-ID, X-Tenant-ID）；
   • 后端微服务拦截器必须验证请求来源合法性，严防外部恶意公网流量直连伪造内部头造成水平越权。

20. 并发控制与 Goroutine 安全红线 (Goroutine Safety)

核心红线 1：Goroutine Panic 拦截

所有新启动的后台 Goroutine，必须在函数首行使用 defer-recover 拦截 panic，严防协程崩溃击垮整个微服务进程：

go func() {
    defer func() {
        if r := recover(); r != nil {
            logx.WithContext(ctx).Errorf("goroutine panic recovered: %v, stack: %s", r, debug.Stack())
        }
    }()
    // 具体的异步处理逻辑...
}()

核心红线 2：循环变量闭包捕获

注意循环变量闭包捕获陷阱，并发时必须显式作为参数传入协程：

for _, item := range list {
    go func(val ItemType) {
        process(val)
    }(item)
}

• 包含并发逻辑的代码变动，必须执行 go test -race ./... 进行竞态检测。

21. 异步 Worker 服务的控制面与高吞吐批处理引擎

🚨 架构规范： 异步 Worker / 后台巡检 Daemon 进程在生产架构中绝不允许退化为孤立的裸脚本进程，必须具备标准的 HTTP 控制面契约（worker.api）与生产级批处理引擎。

21.1 容器健康探针与控制面

1. 健康检查端点：
   • /worker/health、/worker/ping：为 Kubernetes 提供存活（Liveness）与就绪（Readiness）探针支持，异常时自动重启自愈；
2. 运维管理与手动触发端点：
   • /worker/admin/trigger/archive：线上任务积压时，供运维手动强制触发巡检归档；
   • /worker/admin/trigger/flush：紧急停机前，手动触发内存通道残余批量刷盘落库；
   • /worker/admin/trigger/table-provision：手动预建指定月份的物理分表。

21.2 高吞吐批量异步削峰刷盘流水线 (Double-Trigger Batch Flusher)

针对高频写入场景（如实时聊天消息、行为埋点、操作流水），单条直接打库会打满 MySQL 连接池并导致 IOPS 耗尽。必须采用双触发批量刷盘流水线：

生产写入 (Logic / RPC)
  ↓ 非阻塞投递
内存缓冲 Channel (chan Item, 容量 10000)
  ↓
Worker Batch Flusher
  ├── 条件 1: 缓冲条数达到 batch_size (如 200 条) → 触发批量 INSERT
  └── 条件 2: 计时达到 flush_interval (如 200ms) → 即使不足 200 条也强制落库

• 优雅停机排空 (Graceful Drain & Flush)：服务收到 SIGTERM 时，先关闭输入 Channel，将当前缓冲区内的残余消息全部批量写入数据库后再退出，实现零数据丢失。

21.3 零 MySQL 慢查的定时巡检引擎 (Zero-Slow-Query with Redis ZSet)

• 痛点反模式：严禁在数百万级的大表上运行周期性定时扫描（如 SELECT ... WHERE status = 1 AND updated_at < ...），这会导致严重的慢查询与行锁冲突；
• 标准范式：使用 Redis ZSet 时间轴索引（Member 为业务主键，Score 为到期截止时间戳）：
  • 定时轮询调用 ZRangeByScoreWithScores 拉取已超时的少量任务（如 LIMIT 0, 100）；
  • 业务处理完成（如状态变更、资源释放）后，原子调用 ZRem 移出时间轴；
  • 全程对 MySQL 保持零周期性慢查。

22. 长连接网关与实时通信架构规范 (Real-Time Gateway & Messaging)

针对 WebSocket 长连接、IM 实时聊天或实时状态机推送服务：

22.1 单调递增序号发号器与冷启动自愈 (Monotonic SeqID & Recovery)

• 严格保序需求：同一个会话或频道的连续消息，必须具备绝对严格单调递增的序列号（seq_id），防范网络乱序；
• Redis INCR 驱动：正常状态下通过 Redis 原生 INCR {project}:seq:{channel_id} 高性能发号；
• DB 回源原子冷启动自愈 (Recovery)：
  • 若 Redis 发生内存淘汰、服务重启或跨数月后重新激活旧会话，发号器缓存缺失；
  • 严禁直接从 1 开始发号（会导致序号倒挂或主键冲突！）；
  • 必须查询数据库中当前频道的最大序号 SELECT COALESCE(MAX(seq_id), 0) FROM messages WHERE channel_id = ?；
  • 通过 Redis Lua 脚本原子性初始化发号器水位（仅当 Key 不存在时 SET 并附加 TTL），随后继续递增自增，实现无感自愈。

22.2 客户端消息幂等与 3 步 ACK 闭环 (3-Step ACK)

1. 客户端生成 client_msg_id（UUID）：作为上行请求幂等凭据，服务端通过 Redis / 唯一索引校验，防止网络超时重试导致消息重复入库；
2. 3 步 ACK 状态机：
   • Step 1: Server ACK：服务端接收并持久化成功，立即返回该消息服务端分配的唯一 ID 与 SeqID（前端状态置为“已发送”）；
   • Step 2: Peer Delivered ACK：对端长连接在线并成功推流投递（前端状态置为“已送达”）；
   • Step 3: Read ACK：对端用户打开窗口产生已读行为，上报已读游标，更新未读数（前端状态置为“已读”）。

22.3 长连接生命周期与多端互斥踢下线 (Kick-out)

1. 多端互斥策略：当同一账号在另一台新设备建立长连接时，网关检测到已存在旧连接，必须向旧连接发送 kick_out 帧（告知原因），随后优雅主动断开旧 Socket，将在线路由指向新连接；
2. 心跳超时与僵尸连接清理：双向 Ping-Pong 探活，超过 2~3 个心跳周期未收包的连接判定为僵尸连接，服务端强制主动 Close 并清理 Redis 路由表。

23. 全链路排障、上下文萃取与日志分流规范 (Structured Logging & Log Sinks)

23.1 全链路 TraceID 透传

• 每个外部请求进入网关时，必须分配或提取全局唯一的 request_id（推荐采用 ULID 或 UUID）；
• 跨 HTTP、gRPC RPC、WebSocket、异步任务全链路显式透传，所有业务日志必须自动携带 request_id 字段。

23.2 5 大物理日志文件分流标准

生产环境严禁将所有日志混合输出到单个日志文件，必须进行物理分流：

23.3 敏感字段动态脱敏 (Data Masking)

• 脱敏红线：日志打印拦截器必须对敏感数据进行正则掩码脱敏；
• 严禁明文打印：密码（Password）、鉴权令牌（Token/JWT）、API 密钥（SecretKey）、身份证号、银行卡号、手机号（中间 4 位必须打码）。

24. Docker 容器化多环境部署与优雅停机 (Docker & Graceful Shutdown)

24.1 多阶段通用 Dockerfile 范式

# 阶段 1: 编译构建阶段 (Builder)
FROM golang:1.22-alpine AS builder
WORKDIR /app
RUN apk add --no-cache git make
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o /app/bin/service ./service.go

# 阶段 2: 生产运行阶段 (Runner)
FROM alpine:3.19
RUN apk --no-cache add ca-certificates tzdata
ENV TZ=Asia/Shanghai
WORKDIR /app
COPY --from=builder /app/bin/service /app/service
COPY --from=builder /app/etc /app/etc
# 暴露业务端口与探针端口
EXPOSE 8080
ENTRYPOINT ["/app/service", "-f", "etc/service.yaml"]

24.2 容器进程 PID 1 与信号透传红线

• 关键陷阱：在编写 Docker 入口脚本（如 entrypoint.sh）时，绝对禁止直接使用 sh -c /app/service！这会导致 shell 进程成为 PID 1，从而阻断 Kubernetes 发送的 SIGTERM 终止信号，微服务无法优雅停机，最终在超时后被 SIGKILL 强杀，导致内存中的消息刷盘失败！
• 正确规范：必须使用 exec 替换进程映像：

  #!/bin/sh
  # 正确：使用 exec 让 Go 二进制进程直接接管 PID 1
  exec /app/service -f "$CONFIG_PATH"
  

25. 多租户系统隔离规范 (Multi-Tenant Systems)

1. 租户凭证自闭环：租户身份（tenant_id）必须从认证 Context 中提取，禁止直接信任前端可被篡改的传参；
2. 查询条件必带租户过滤：业务表增删改查 SQL，必须无条件携带 tenant_id = ? 约束，严防跨租户越权数据泄漏。

26. 性能调优与查询守则 (Performance & SQL Rules)

1. 基于数据与 Profiling 优化：拒绝凭直觉负优化，善用 go test -bench、pprof；
2. 数据库性能优先看执行计划：使用 EXPLAIN 检查索引命中（key）、扫描行数（rows）与临时表使用；
3. 高频业务路径严禁无脑 SELECT *，必须使用 Select("id", "status", "created_at") 仅投影必要字段；
4. 防深度分页：大数据量（数百万级）大表分页，严禁大 Offset，应使用 Keyset/游标分页：

   WHERE id > ? ORDER BY id ASC LIMIT ?
   

27. 单元测试规范 (Testing)

• 优先采用表格驱动测试（Table-Driven Tests）：覆盖正常流、临界边界、非法输入、空指针防御与错误降级；
• 交付前质量检查命令集：

  go test ./...        # 运行所有单元测试
  go test -race ./...  # 竞态安全检查 (并发改动必跑)
  gofmt -w .           # 规范化代码格式
  go vet ./...         # 官方静态分析检查
  

28. 代码注释与文档化规范 (Commenting Standards)

1. 包级注释：每个 package 主文件顶部必须包含中文包级注释，说明职责、导出实体与注意事项；
2. 结构体与字段注释：说明实体的业务含义；每个字段编写行尾注释，写明含义、单位、取值范围或约束；
3. 函数与方法注释：第一句话以函数名开头，说明功能意图、关键入参业务语义、返回值及可能返回的错误；
4. 行内关键注释：在状态机流转、并发加锁、事务边界、算法核心逻辑处解释 Why & How，严禁无效废话注释。

29. 规范代码风格 (Code Style)

1. 卫语句（Guard Clauses）优先：尽早返回，降低代码圈复杂度与嵌套层级；
2. 拒绝单实现接口滥用：禁止为了写接口而写单实现接口，仅在存在多实现、跨系统 Mock 或明确架构边界时定义 interface。

30. AI 常见错误与避坑指南 (Common AI Mistakes to Avoid)

AI 代理在编写 go-zero 代码时必须严防以下 8 大典型错误：

1. 擅自篡改底层架构：把 go-zero 路由强行改成 Gin、Fiber 或 Kratos 风格；
2. 直接手工修改生成代码：手动修改 internal/handler/ 或 *_gen.go，导致下次生成被全量覆盖；
3. 滥建冗余接口：为每个 Logic 凭空建立单实现接口；
4. 随处定义全局数据库客户端：搞出 var DB *gorm.DB 全局单例，破坏依赖注入；
5. 对既有通用工具视而不见：重新造轮子实现既有公共包已有的分页或工具；
6. 过度设计架构：在简单 CRUD 模块强塞复杂的六边形架构或 CQRS；
7. 全库格式化污染 Git 提交：改动单接口却顺带格式化全库几十个文件，破坏 git blame；
8. 随意拉升依赖版本：无端升级主要依赖库，破坏项目既有兼容性。

31. 交付完成定义 (Definition of Done - DoD)

在宣布任务完成前，对照以下清单自检：

• 已透彻理解项目既有分层架构与上下文
• 严格遵守单一职责，单文件未超过 500 行，一个用例对应一个 Logic
• 涉及接口变动已正确更新 .api / .proto 源契约
• 涉及生成代码已通过 Makefile 受控重新生成，未手改生成文件
• 核心业务逻辑收敛于 Logic 层，未在 Handler 写业务
• 枚举符合三层转换标准，无魔法数字或硬编码字符串判断
• 数据库 CRUD 与缓存实现正确，无 SQL 注入与全表更新风险
• 分布式锁使用随机 UUID + Lua 脚本原子释放
• 错误处理遵循 5 大场景规范，跨层 %w 包装，无 _ 忽略
• 认证鉴权与租户数据隔离安全受检
• 单元测试已编写或更新，覆盖核心与边界用例
• gofmt 已执行，go test ./... 运行通过
• git diff 严格复查无误，无无关文件混入，无明文密钥泄露

32. 决策优先级仲裁 (Priority Rules)

面临方案分歧时，严格按下述优先级裁决：

1. 用户的明确指令与要求 (User's Explicit Requirements)
   ↓
2. 当前项目既有的具体架构规范与已有约定 (Existing Project Architecture & Conventions)
   ↓
3. go-zero 官方标准范式 (go-zero Conventions)
   ↓
4. Go 语言惯用语法 (Idiomatic Go)
   ↓
5. 通用软件工程最佳实践 (General Engineering Best Practices)

33. 黄金准则 (The Golden Rule)

针对 go-zero 工程开发，永恒的核心法则只有一条：

既有项目代码是第一事实来源 (The existing project is the primary source of truth)。

• 动手造轮子前，先在已有项目中找示例；
• 修改生成的代码前，先找到它的定义源头；
• 引入第三方库前，先检索仓库既有依赖；
• 更改接口契约前，先评估所有调用方影响；
• 始终保持改动：最小精准、语义明确、测试覆盖、稳定兼容！

6. Bug 分析、排查与调试武器库 (Troubleshooting & Debugging Guide)

在排查 Go 与 go-zero 微服务生产缺陷时，必须遵循 systematic-debugging 根因定位 SOP，并熟练运用以下语言专属调试武器库：

6.1 并发竞争与协程泄漏排查 (Data Race & Goroutine Leak)

• 静态竞态检测 (Data Race Detection)： 在运行单测或本地模拟压测时，必须开启 -race 标志：

  go test -race -v ./...
  

• Goroutine 堆栈转储与泄漏诊断： 若服务出现内存缓慢上升、连接不释放，通过引入 net/http/pprof 查看堆栈：

  # 抓取当前正在运行的 Goroutine 数量与调用栈
  curl -s http://127.0.0.1:6060/debug/pprof/goroutine?debug=2 | grep -A 10 "goroutine"
  

  排查重点：检查是否有通道（channel）无接收方导致生产者永不退出，或 context.WithCancel 遗漏 defer cancel()。

6.2 未捕获 Panic 与进程崩溃排查

• 排查红线：若进程异常重启或服务中断，第一时间检索启动日志中的 panic: 关键字；
• 定位原则：检查崩溃 Goroutine 栈顶的第一行业务代码。所有后台 Goroutine 必须使用 threading.GoSafe 或手动包装：

  go func() {
      defer func() {
          if r := recover(); r != nil {
              logx.WithContext(ctx).Errorf("Background Goroutine Recovered: %v, stack: %s", r, debug.Stack())
          }
      }()
      // 执行业务逻辑...
  }()
  

6.3 慢调用与性能瓶颈诊断 (Slow Queries & Bottlenecks)

• go-zero 慢日志自动捕获： go-zero 框架默认会对超过 500ms 的 API/RPC 请求及超过 100ms 的数据库操作输出 [SLOW-SQL] 或 [SLOW-RPC] 告警日志，直接根据 TraceID 提取上下文全链路；
• MySQL 慢查与连接池饱和： 若出现 context deadline exceeded 或 driver: bad connection，检查连接池 MaxOpenConns 与 MaxIdleConns 配置，并利用 EXPLAIN 分析索引失效原因。

6.4 缓存不一致与分布式锁排查

• 缓存穿透与击穿排查：检查缓存失效后是否有大量并发直接击垮底层 DB；必须使用 collection.NewCache 或带有 SingleFlight 防击穿机制的驱动；
• Redis 分布式锁死锁：检查持有锁的业务逻辑是否发生长耗时阻塞导致锁自动超时释放（需确认看门狗续期或严格的超时上限）。

7. 微服务高可用进阶：K8s 优雅停机与上帝文件拆分红线 (Advanced Production Guardrails)

7.1 K8s 容器化优雅停机标准 (Graceful Shutdown)

在 Pod 缩容、滚动更新或发布上线时，为避免长连接被强制掐断或处理中的事务中断，必须实现平滑退水：

// 注册进程退出信号拦截
proc.AddShutdownListener(func() {
    logx.Info("Shutdown signal received, waiting for pending tasks...")
    // 1. 停止接受新入请求 / 摘流注册中心 (Nacos/Consul/Etcd)
    // 2. 等待处理中的 HTTP/RPC 请求处理完毕 (超时上限 15s)
    // 3. 关闭异步 Worker 管道消费
    // 4. 释放 Redis 连接与 DB 连接池
    logx.Info("Graceful shutdown completed.")
})

7.2 上帝文件拆分红线 (Anti-God-Files - 核心红线)

• 单文件行数上限：任何单一 logic.go 或 model.go 文件严禁超过 800 行；
• 拆分原则： 若某个 Logic 涉及多个子操作（如订单支付完成后的发短信、加积分、履约推送），必须将子操作拆解至专有的独立 Sub-Logic 或领域服务中，禁止在一个方法中堆砌成百上千行代码。