# Go Backend Technical Design

> Go 后端技术设计：包边界、handler-service-repository 分层、API 契约、存储设计、事务、一致性、可观测性、发布策略与 ADR 权衡。需求稳定后使用。

- Skill: `gmh5225/go-backend-technical-design` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add gmh5225/go-backend-technical-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gmh5225/go-backend-technical-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: gmh5225 (https://skillmd.com/u/gmh5225)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/gmh5225/go-backend-technical-design

---


# Go 后端技术设计

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

## 适用时机

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

## 输入

按优先级定位需求文档：

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

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

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

## 设计先行硬规则

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

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

## 目标

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

## 设计文档结构

使用以下结构：

```md
# 技术设计

## 背景

## 需求映射表

| 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 是否有边界、可取消、可观测？
- 共享可变状态是否同步或已避免？
- 错误类型与包装规则是否已定义？
- 配置归属是否明确？

## 推荐包结构

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

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