DEV-MERGE-LEGACY-BACKEND-2026/EXAMPLES.md

参考样例索引 + GoDoc 注释标准

本文件是 backend/README.md 铁律 11（注释标准） 的落地模板与样例清单。 所有样例代码可编译（go build ./... + go vet ./... 全绿，本地 go 1.27.x）， 每个导出符号均带 GoDoc 中文注释（功能说明+样例 / 入参逐项 / 出参逐项+异常场景）。 架构决策依据见 ../unified/01-architecture/backend-technical-architecture.md。

---

1. 样例包清单

包	路径	落地的架构规格节	承载的 ADR / 铁律	核心导出
统一响应	internal/infra/response	§3.1 接口规范	铁律 6（HTTP 恒 200 + body code）	R / PageData / OK / Page / Fail / ParsePage
三层错误	internal/infra/errors	§3.2 异常处理	错误码分段 1xxx–5xxx	AppError / New / WithCause / sentinel ErrNotFound 等
多租户作用域	internal/infra/scope	§3.5 作用域注入	铁律 2（强制作用域）	Scope / Set / FromFiber / BaseRepo / NewBaseRepo
入参校验	internal/infra/validator	§3.1 入参惯例	铁律 7（validateReq 语义）	Validate
配置管理	internal/infra/config	§3.4 配置	ADR-015（12-factor）	Config / Load / EnsureRuntimeDirs
身份主键	internal/identity/id	§7.1	ADR-013（ULID）	NewCanonicalUserID / NewCanonicalUserIDAt / Validate / Length
密码凭证	internal/identity/credential	§3.8 / §7.4	ADR-016（argon2 惰性升级）	Check / HashArgon2 / VerifyArgon2 / Result / HashVersion*
SSO token	internal/identity/token	§7.2	ADR-014（SSO 最小可行）	Issuer / Claims / Issue / Verify / Rotate / RevokeAll
异步任务	internal/task	§3.7	统一 DB 任务表	Task / Repo / Enqueue / Claimable / Claim / Done / Fail / ReclaimStale

规划待建（尚无代码，目录已占位）：cmd/api（装配入口）、internal/org（多租户+7 角色）、 internal/academic（教务域）、internal/teaching（教学域）、internal/ai（Agent 消费方）。 新增这些域时，必须先对齐本文件的注释标准再写业务逻辑。

---

2. GoDoc 注释标准（三段式）

每个导出的结构体 / 函数 / 方法 / 常量 / 错误变量，注释必须覆盖三段；缺一段视为不完整：

① 功能说明（用途 + 核心逻辑）

• 一句话说清"做什么 + 为什么这样设计"，点明对应的架构规格节 / ADR / 铁律。
• 导出项（被其它包调用）必须附典型使用样例（多行 // 代码块），让读者不翻实现就能上手。
• 设计取舍 / 坑点用"为什么"句式说明（例："为什么不用 err != nil 判""为什么走 c.Locals 不走 context"）。

② 入参说明（逐项）

• 每个参数：- 参数名 类型：含义；约束/取值范围。
• 标注必填/可空、默认值、上限钳制、敏感项（密钥/密码）。
• 无参函数写"入参：无"，不留空。

③ 出参说明（逐项 + 异常场景）

• 每个返回值：- 名称 类型：含义。
• 异常场景单列：哪些输入/状态会返回 error / 特殊值（nil、false、dead），以及调用方该如何处理。
• 错误要说明"降级还是 fail-fast""是否 fail-closed"（安全相关明确标注）。

包级注释（文件顶部）

• 第一段一句话定位（本包解决什么）。
• 背景 / 数据来源 / 关键约束（ADR、风险登记册条目）。
• 典型使用完整链路示例（跨包协作时给出端到端调用片段）。

与实现一致性（强制）

• 改实现必须同步改注释；注释描述的行为与代码不符 = bug。
• 不写"显然"的废话注释（// 加 1）；只写"读代码看不出来"的设计意图、约束、坑。
• 中文用规范标点；代码片段内标识符保持原样不翻译。

---

3. 注释模板（复制即用）

// <导出符号> <一句话功能>（对应架构规格 §X / ADR-XXX / 铁律 N）。
//
// 典型使用（调用方）：
//
//	<2~6 行可运行的调用片段>
//
// 入参：
//   - name1 type1：含义；约束（必填/可空/默认值/上限）。
//   - name2 type2：含义；敏感项标注（如"走环境变量，勿入库"）。
//
// 出参：
//   - ret1 type1：含义。
//   - ret2 error：以下场景非 nil——
//     - 场景 A：处理建议（降级/重试/fail-closed）。
//     - 场景 B：处理建议。
//
// 异常场景：
//   - 边界输入 X：行为 Y（为何这样，而非报错）。

---

4. 构建与一致性校验

# go.mod `go 1.27`（语言级别 + 最低工具链）；本机 go 1.27.x 直接构建。
# 依赖保持初版锁定版本（validator v10.27.0 等），升 1.27 后实测无意外升级。
go build ./...          # 必须 0 错误
go vet   ./...          # 必须 0 告警（1.27 起默认含 stdversion 检查）
GOTOOLCHAIN=local go build ./...   # 强制本地工具链（防 CI 误拉非预期工具链）

# 一致性自检（注释与实现对齐的最低门槛）
go doc ./internal/infra/response     # 查看包文档是否完整渲染

新增业务域 checklist：

1. 目录落在正确域（academic/teaching/org/ai），不进 infra（横切）或反向依赖。
2. 数据访问经 Repository + scope.BaseRepo.scoping（铁律 2），不裸查。
3. Service 返回 *errors.AppError sentinel（铁律，不裸抛 gorm 原错）。
4. Handler 用 response.OK/Page/Fail（铁律 6）+ validator.Validate（铁律 7）。
5. 每个导出符号带三段式 GoDoc（铁律 11），改实现同步改注释。
6. go build / go vet 全绿后方可提交。