Go 后端技术设计

需求分析完成且稳定后使用，用于规划实现细节。

适用时机

• 用户说"出一个技术方案" / "technical design" / "设计一下这个功能"

• 需求分析已完成，进入实现规划阶段

• 需要确定包结构、接口契约、存储方案、事务边界

• 涉及跨服务集成、异步任务或复杂一致性要求的功能

输入

按优先级定位需求文档：

• 对话上下文：若当前会话已包含需求分析结果，直接使用，无需读取文件

• 用户提供路径：用户在消息中指定了文档路径，直接读取

• 自动发现：在当前工作目录中查找最近修改的需求文档

自动发现：查找最近修改的需求文档

ls -t $(find . -maxdepth 3 ( -name "requirement" -o -name "需求" ) -name "*.md" 2>/dev/null) 2>/dev/null | head -5

若自动发现到多个候选文件，列出并让用户确认使用哪份。若未找到任何文件，提示用户提供路径或在当前会话中粘贴需求内容。

设计先行硬规则

在技术设计文档得到确认之前，禁止进入编码阶段。

• 技术设计必须覆盖所有 Req# 到实现组件的映射

• 设计文档需要用户显式确认（"OK" / "同意" / "可以开始"）后才视为已批准

• 如果用户直接要求编码，先输出简化设计摘要并等待确认，再开始编码；如用户明确跳过，标记为 SPEC-skipped ，后续 review 时重点检查是否偏离需求

• 设计变更必须先更新文档再更新代码

目标

• 将需求转化为可执行的设计方案

• 保持设计的具体性，足以支撑实现规划

• 显式说明权衡取舍

设计文档结构

使用以下结构：

技术设计

背景

需求映射表

变更影响摘要

设计方案（流程图）

包与职责划分

API 或 RPC 契约

数据模型与持久化

一致性与事务模型

错误模型

可观测性

安全控制

发布与回滚

备选方案

需求差异管理

技术设计可以基于工程判断对需求做简化或分期，但不得静默丢弃需求：

• 对需求文档中每条 Req# 和 AC#，设计文档必须有对应处理（实现 / 显式延迟 / 显式拒绝）

• 若设计简化了某条需求（如移除参数、缩减场景），必须在需求映射表或变更影响摘要中标注：AC8: 延迟至后续迭代——理由：MVP 范围收窄 或 R5: 设计拒绝——理由：...

• 禁止出现需求文档有但设计文档中无踪迹的条目

设计规则

分层明确

典型服务定义以下层次：

• transport / handler 层

• application service 层

• domain logic 层

• repository / gateway 层

• 后台任务层（如有）

写流程必须显式

每个写操作流程需记录：

• 校验

• 鉴权

• 领域检查

• 持久化

• 异步副作用

• 响应映射

失败路径与成功路径同等重要

始终明确：

• 重试归属（谁负责重试）

• 超时归属（谁设置超时）

• 幂等键或去重策略

• 部分失败行为

• 补偿机制（如需要）

Go 专项清单

• context.Context 是否从入口一路传递到下游调用？

• 接口是否只在依赖边界引入？

• 事务是否收窄到最小范围？

• goroutine 是否有边界、可取消、可观测？

• 共享可变状态是否同步或已避免？

• 错误类型与包装规则是否已定义？

• 配置归属是否明确？

推荐包结构

仅在适合当前仓库时采用：

internal/ transport/http/ app/ domain/ repository/ jobs/ platform/

参考资料

• Gin HTTP 服务，参见 references/gin-http.md

• gRPC 优先服务，参见 references/grpc.md

• 存储变更较重，参见 references/persistence.md

交接

设计文档输出完成后，在对话末尾告知用户可选的后续步骤，等待用户明确指示后再继续，不得自动进入下一阶段：

• /go-backend-architecture — 系统边界或演进路径尚未确定时（可选）

• /go-backend-reviewer — 实现完成后对照本设计进行代码审查