# Fs Spec Backend

> 全栈·后端方向实现规格生成器。REST/GraphQL/gRPC API、微服务、消息队列(Kafka/RabbitMQ)、任务调度、认证授权(OAuth/OIDC/JWT)、API 网关、文件存储、支付、邮件。用户提"接口设计、服务端、微服务、后端规范"时使用。属 it-project-spec-generator 体系。

- Skill: `wufufu770/fs-spec-backend` (Agent Skill)
- Install (CLI): `npx skillmds@latest add wufufu770/fs-spec-backend`
- Raw SKILL.md: https://api.skillmd.com/api/skills/wufufu770/fs-spec-backend/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- License: MIT
- Author: wufufu770 (https://skillmd.com/u/wufufu770)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/wufufu770/fs-spec-backend

---


# 后端实现规格生成器

## 角色

资深后端架构师：把服务需求翻译成接口级、数据流级可开工可验收的规格。非 UI 领域：铁律 2 落地为状态机，铁律 3 不适用。

## 生成前置（每次必做）

按序读取本 skill 目录同级的 `_spec-core/` 下 `core-laws.md` → `protocol.md` → `structure.md` 并遵照执行；内核不可读时降级为无内核模式：直接按本 skill 领域骨架生成，全部精确值标 [待验证] 并在文末注明「核心铁律未加载」。

## 章节骨架（叠加于通用 10 章；第 4 章架构、第 5 章功能为最重两章）

```
Requirements → Installation → Configuration（环境变量表）→
API Reference → Errors/错误码 → Examples → Deployment → Security → Performance → FAQ
```

## 子形态要点

| 子形态 | 规格必含 |
|--------|---------|
| REST API | 端点表（`方法\|路径\|认证\|请求体\|成功响应\|错误码`）、HTTP 状态码枚举（200/201/204/400/401/403/404/409/422/429/500/503）、分页约定（page/page_size 或 cursor）、排序过滤语法、速率限制头（X-RateLimit-*）、幂等键、统一错误体 `{code, message, details, trace_id}` |
| GraphQL | Schema 组织（type/query/mutation/subscription）、权限指令、connection 分页规范、成本与 depth 限制、缓存策略、N+1 防护 |
| gRPC | proto 包命名规范、服务方法清单表、流类型、错误码映射（google.rpc）、超时与重试策略、负载均衡 |
| 消息队列 | topic/queue 清单表（分区数、副本、保留策略）、消费组命名、消息 schema 版本化、死信队列、重试退避、幂等生产者/消费者、顺序保证说明 |
| 微服务 | 服务清单表（服务名→职责→端口→存储→SLA）、服务间通信契约、服务发现、熔断限流参数（如 5xx 连续 10 次熔断 30s）、分布式事务取舍、trace 传播头 |
| Serverless | 函数清单（触发器→内存→超时→并发上限）、冷启动预算、配置外置、结构化日志、优雅降级 |
| 任务调度 (Celery/Temporal) | 任务清单、队列/worker 并发、重试策略（次数+退避）、定时任务 cron 表、幂等、死信 |
| ORM/数据库访问 | 实体映射表、迁移策略、查询规范（禁 N+1）、事务边界、连接池参数表 |
| 缓存 | 缓存键规范、TTL 表（每类数据）、失效策略（主动/被动）、一致性级别、击穿/雪崩防护 |
| 认证授权 | 授权流程（Authorization Code + PKCE）、token 生命周期表（access/refresh 时长、刷新窗口）、scope 表、角色×资源权限矩阵、会话管理 |
| API 网关 | 路由表（路径→上游）、插件清单（限流/认证/日志）、健康检查 |
| 文件存储 (S3) | 桶结构、对象命名规范、生命周期规则、上传方式（预签名 URL/分片）、访问控制 |
| 支付 | 支付方式清单、回调验签流程、订单号幂等、对账、退款状态机（pending/success/failed/refunded）、金额精度（分） |
| 邮件 | 模板清单、发送队列、退信处理、SPF/DKIM/DMARC 要求、频率限制 |

## 领域增补铁律

8. 所有写接口 MUST 幂等（Idempotency-Key 头或业务唯一键）。
9. 错误响应 MUST 用统一格式 `{code, message, details, trace_id}`，MUST NOT 返回裸异常堆栈。
10. 上游调用 MUST 设连接/读/写三档超时（默认 3s/5s/10s），并声明重试策略与幂等前提。
11. 敏感字段（密码/token/密钥）MUST NOT 出现在日志、响应体、错误信息中。

## 数据库变更规范

- 迁移脚本 MUST 可回滚且先在 staging 验证；破坏性变更（删列/改类型）MUST 走 expand-migrate-contract 三步。
- 每张核心表给：索引清单（含理由）、预估行数量级、增长速率。

## 验收惯例

契约测试（OpenAPI/schema 校验）；集成测试覆盖每端点的成功/参数错/未认证/限流四类路径；负载测试给 P95/P99 曲线图要求；混沌项（依赖宕机时的降级行为）写入验收表。

## 开工检查单默认项

技术栈一行 / 目录草案（routes|services|repositories|migrations|tests）/ 最先实现的 3 个文件（配置加载 → 健康检查端点 → 一条垂直切片 CRUD）/ 最低验收 = 核心端点契约测试绿。

## 不适用（When NOT to use）

- Web 界面与交互细节归 fs-spec-frontend。
- CI/CD、容器编排、可观测性建设归 fs-spec-devops。
- 数据管道与模型服务归 fs-spec-data-ai。