go-backend-technical-design

name	go-backend-technical-design
description	Go 后端技术设计：包边界、handler-service-repository 分层、API 契约、存储设计、事务、一致性、可观测性、发布策略与 ADR 权衡。需求稳定后使用。
allowed-tools	Read, Bash, Glob, Grep
disable-model-invocation	true
context	fork

Go 后端技术设计

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

适用时机

• 用户说"出一个技术方案" / "technical design" / "设计一下这个功能"
• 需求分析已完成，进入实现规划阶段
• 需要确定包结构、接口契约、存储方案、事务边界
• 涉及跨服务集成、异步任务或复杂一致性要求的功能

输入

按优先级定位需求文档：

1. 对话上下文：若当前会话已包含需求分析结果，直接使用，无需读取文件
2. 用户提供路径：用户在消息中指定了文档路径，直接读取
3. 自动发现：在当前工作目录中查找最近修改的需求文档

# 自动发现：查找最近修改的需求文档
ls -t $(find . -maxdepth 3 \( -name "*requirement*" -o -name "*需求*" \) -name "*.md" 2>/dev/null) 2>/dev/null | head -5

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

设计先行硬规则

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

• 技术设计必须覆盖所有 Req# 到实现组件的映射
• 设计文档需要用户显式确认（"OK" / "同意" / "可以开始"）后才视为已批准
• 如果用户直接要求编码，先输出简化设计摘要并等待确认，再开始编码；如用户明确跳过，标记为 SPEC-skipped，后续 review 时重点检查是否偏离需求
• 设计变更必须先更新文档再更新代码

目标

• 将需求转化为可执行的设计方案
• 保持设计的具体性，足以支撑实现规划
• 显式说明权衡取舍

设计文档结构

使用以下结构：

# 技术设计

## 背景

## 需求映射表

| Req# | 设计组件 | 验证方式 |
|------|---------|---------|
| R1   | service.CreateOrder() | 单元测试: TestCreateOrder |
| R2   | middleware.RateLimiter | 集成测试: TestRateLimit |

## 变更影响摘要

| 变更范围 | 影响组件 | 影响评估 | 回滚方案 |
|----------|----------|----------|----------|
| 新增 API | transport 层 | 低风险，纯新增 | 关闭路由注册 |
| Schema 变更 | repository 层 | 需要迁移脚本 | 执行回滚迁移 |

## 设计方案（流程图）

## 包与职责划分

## 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 — 实现完成后对照本设计进行代码审查