| name | service-constraints |
| description | 后端服务运行时治理——启动 fail-fast；优雅生命周期（SIGTERM→排空→超时强退→LIFO 释放）；非幂等写经幂等键；跨进程必设超时、重试仅幂等且退避。触发：启动/关闭、健康检查、写幂等、下游超时/重试、错误传播。跳过：配置载体与密钥分层（→config-constraints）、代码风格（→golang-constraints）、API 契约（→api-design）、可观测性（→observability）。 |
后端服务工程约束
适用于：后端服务的启动/关闭生命周期、写操作幂等、超时重试、错误传播等运行时治理的设计、实现、文档与 review。原则技术栈无关，示例用 Go。
边界（去耦合，避免重复）：配置载体选择 / 密钥分层 / 热更 fail-safe → config-constraints；代码风格 / 三层架构 → golang-constraints；对外错误响应格式与 A-BBB-CCCC 错误码体系 → api-design；日志 / 链路 / 指标 → observability-constraints；认证 / 授权 → auth-constraints / authz-constraints。本 skill 只管它们未覆盖的「服务运行时骨架」。
定位：技术框架定型，钉死「机制骨架」（【硬】必守），不绑「业务策略」（【软】给能力、由项目按业务选）。
0. 触发与跳过
TRIGGER：搭建启动/关闭流程、健康检查；实现写操作幂等、下游调用超时/重试；设计 error 传播与边界转码；文档 / PRD / 设计 / review 涉及上述。
SKIP：配置载体与密钥分层（→ config-constraints）、纯代码风格/架构（→ golang-constraints）、对外 API 契约（→ api-design）、可观测性信号装配（→ observability）。
1. 启动校验 fail-fast【硬】
- 单点加载 + 启动校验 fail-fast：配置在进程启动时一次性加载并校验，缺失/非法即启动失败，禁带病运行到首次使用才报错。
2. 优雅生命周期【硬】
- 启动：依赖（DB/缓存/下游）就绪前不对外提供服务。
- 健康检查分离：
liveness（进程是否活着，挂了重启）与 readiness（是否可接流量，未就绪摘流量）语义分开，禁混为一个。
- 优雅关闭（收到 SIGTERM）：停止接收新请求 → 排空在途请求 → 超时上限后强退 → 资源 LIFO 释放（在途 → 连接池 → 上报通道）。
- 关闭必须有超时兜底，禁无限等待在途；释放错误聚合上报、不阻断后续释放。
3. 写操作幂等【硬】
- 非幂等写（POST 创建、扣款、发消息等）必须支持幂等键（
Idempotency-Key）。
- 首次结果落库 + 重放：同一幂等键的重复请求返回首次执行结果，不重复执行副作用。
- 至少一次投递场景必去重：MQ 消费、支付回调、客户端重试都可能重复送达，消费侧按业务唯一键/幂等键去重。
- 呼应
api-design：PUT/DELETE 语义天然幂等，POST 靠幂等键补齐。
if rec, ok := idem.Lookup(ctx, key); ok {
return rec.Result, nil
}
4. 超时、取消与重试【硬】
- 每个跨进程调用（DB / RPC / HTTP / 缓存）必设超时，禁无限等待。
- context 传播 deadline / cancel：上游超时或取消，向下游透传，及时释放资源（呼应
observability 的 ctx 透传）。
- 重试四条件：指数退避 + 抖动、有次数上限、仅对幂等操作或带幂等键、只重试可重试错误（超时 / 5xx /
Unavailable），不可重试错误（4xx / 参数错）直接失败。
- 禁裸重试放大故障（重试风暴）；高频失败下游考虑熔断（fail-fast）。
5. 错误传播【硬】
- wrapping 保留链：
fmt.Errorf("...: %w", err)，禁 %v 断链、禁丢弃原 err。
- 边界层统一转码：内部 error 在服务边界（handler / 拦截器）统一映射为
api-design 的 A-BBB-CCCC，内部传播保留原始 error，禁在底层提前裸抛错误码字符串。
- 禁吞错误（
_ = doSomething() 静默丢弃）；禁裸 panic 扩散——拦截器 recover 并转 ERROR（呼应 observability 级别语义）。
- 哨兵错误判定用
errors.Is、类型提取用 errors.As，禁字符串比对 error message。
6. 留给项目的【软】
框架不钉死，由各项目按业务/规模定：具体超时时长与重试次数/退避参数、健康检查端点路径与就绪判定项、幂等键存储介质（Redis / DB）与 TTL、熔断阈值与策略。
7. 自检清单
