---

name: backend-dev description: | This skill should be used when the user asks to "build a backend API", "design a database schema", "implement authentication", "create a REST endpoint", "develop a microservice", "set up server-side logic", "write API routes", "design system architecture", "implement business logic", "connect to database", "set up middleware", "configure ORM", "write server tests", "deploy backend service", or discusses backend-related tasks including API design, database design, authentication/authorization, server architecture, middleware, error handling, logging, performance optimization, or backend testing. Also triggered by technology-specific requests mentioning "Express", "FastAPI", "Spring Boot", "Django", "Rails", "Gin", "Fiber", "NestJS", "GraphQL", "gRPC", "WebSocket", "PostgreSQL", "MongoDB", "Redis", "JWT", "OAuth", "OpenAPI", "Swagger", "Docker compose backend", or "CI/CD pipeline".

【中文触发场景】

• "写后端接口"、"开发API"、"设计数据库"、"实现登录"
• "搭建后端服务"、"写服务器代码"、"实现业务逻辑"
• "数据库设计"、"表结构设计"、"API文档"
• "后端架构设计"、"微服务拆分"、"接口规范"
• "权限系统"、"中间件"、"错误处理"、"日志"
• "后端测试"、"单元测试"、"集成测试"
• "部署后端"、"Docker化"、"CI/CD配置" allowed-tools: Read, Write, Edit, Bash, Glob, Grep, WebFetch, TaskCreate, TaskUpdate, TaskList

---

Backend Development Professional Workflow

专业后端开发工作流 —— 从需求到部署，结构化、可追溯、可审查。

核心原则

1. 防御性编程 —— 所有外部输入不可信，边界条件显式处理
2. 关注点分离 —— 分层架构（Handler → Service → Repository），每层只做一件事
3. 显式优于隐式 —— 依赖注入、配置外部化、错误显式传播
4. 渐进式交付 —— 先可运行，再优化；先核心路径，再边缘场景

工作流总览

Phase 0: 需求澄清与约束定义  ──→  明确边界、性能目标、部署环境
    ↓
Phase 1: 架构设计             ──→  分层/模块/数据流/技术选型 & 决策记录
    ↓
Phase 2: 核心实现（增量）      ──→  Repository → Service → Handler 由内向外
    ↓
Phase 3: 安全加固             ──→  认证/授权/输入校验/注入防护/速率限制
    ↓
Phase 4: 测试覆盖             ──→  单元 → 集成 → 契约测试（含边界与异常）
    ↓
Phase 5: 审查与改进           ──→  自审查清单 → 性能评估 → 文档收尾

每个阶段的 prompt 模板在 prompts/ 目录中，按需引用。

阶段详细说明

Phase 0: 需求澄清与约束定义

执行 prompts/phase0-clarify.md 中的提问框架，收齐以下信息：

| 维度 | 必须明确的点 | |------|-------------| | 上下文 | 业务场景、用户群体、预期流量 (QPS) | | 技术栈 | 语言/框架/数据库/运行时版本 | | 约束 | 部署方式（容器/Serverless/VM）、团队规模、时间线 | | 接口风格 | REST / GraphQL / gRPC / WebSocket / 混合 | | 数据要求 | 一致性级别、数据量级、是否需要事务 | | 非功能要求 | P99延时、可用性 SLA、审计合规 |

输出文件：.backend-dev/phase0-requirements.json

Phase 1: 架构设计

执行 prompts/phase1-arch.md，输出以下工件：

• 分层架构图 —— Handler / Service / Repository / 中间件栈
• 模块划分 —— 每个模块的职责、边界、依赖方向
• 数据模型 —— 核心 Entity 定义、表关系（ER）、索引策略
• 接口契约草案 —— 端点路径、请求/响应结构、状态码
• 技术选型决策记录 (ADR) —— 每次选型附理由和替代方案
• 风险与缓解 —— 识别数据热点、单点瓶颈、降级策略

输出文件：.backend-dev/phase1-architecture.json

Phase 2: 核心实现

按 Repository → Service → Handler 由内向外顺序，逐层实现：

Request  →  [Middleware]  →  Handler  →  Service  →  Repository  →  DB
                                            │
                                            ↓
                                        外部服务 / 缓存 / 消息队列

每条实现遵循：

1. 先定义接口（interface/trait/type），再实现
2. 显式错误类型 —— 定义领域错误码，不在运行时拼字符串
3. 完备的日志 —— 每个外部调用的入口和出口都记录结构化日志
4. 幂等性考虑 —— 写操作的幂等键（idempotency key）设计

Phase 3: 安全加固

执行 prompts/phase3-security.md 中的安全检查清单，逐项验证：

• 认证策略（JWT / Session / OAuth / API Key）
• 授权模型（RBAC / ABAC / ACL）
• 输入校验（结构化校验库 + 白名单策略）
• 注入防护（参数化查询 / ORM / 输出编码）
• 速率限制与防滥用
• 敏感数据（加密存储、响应脱敏、日志脱敏）
• CORS / CSP / HTTPS 强制

Phase 4: 测试覆盖

执行 prompts/phase4-testing.md，按金字塔模型覆盖：

        ╱╲              手动探索测试
       ╱  ╲             E2E 测试 (关键用户路径)
      ╱    ╲            集成测试 (模块间契约)
     ╱______╲           单元测试 (核心逻辑 + 边界)

每条测试准则：

• 每个 Repository 方法对应一个集成测试
• 每个 Service 公共方法对应单元测试（mock 依赖层）
• 每条 Handler 路径（成功/鉴权失败/参数错误/404）各一个测试
• 错误路径优先级 ≥ 成功路径

Phase 5: 审查与改进

执行 prompts/phase5-review.md，逐项审查：

1. 正确性审查 —— 并发竞态、事务边界、状态机状态遗漏
2. 性能审查 —— N+1 查询、缺少索引、未使用连接池、未分页
3. 可观测性 —— 结构化日志、指标埋点、健康检查端点、追踪上下文传播
4. 文档补全 —— API 文档 (OpenAPI)、README 运行说明、环境变量清单

交叉引用清单

• references/api-design.md —— REST / GraphQL / gRPC 设计规范与对比
• references/db-best-practices.md —— 表设计、索引策略、迁移、连接池
• references/error-handling.md —— 错误类型体系、结构化错误响应、全局异常处理
• references/security-baseline.md —— 安全基线检查表（OWASP Top 10 映射）
• references/struct-export.md —— 阶段间结构化数据传递格式定义

输出规范

所有中间产出统一存放于 .backend-dev/ 目录，按阶段命名：

.backend-dev/
├── phase0-requirements.json    # 需求与约束
├── phase1-architecture.json    # 架构设计方案
├── phase2-impl-record.md       # 实现过程记录
├── phase3-security-report.md   # 安全审查报告
├── phase4-test-report.md       # 测试覆盖报告
├── phase5-review-report.md     # 最终审查报告
└── adr/                        # 架构决策记录（每项决策一个 markdown）
    ├── 001-use-postgresql.md
    └── 002-adopt-repository-pattern.md

注意事项

1. 增量交付 —— 不要一次性生成所有代码。每次围绕一个功能点的完整分层实现（Handler → Service → Repository），提交后继续下一个
2. 不重复造轮子 —— 优先使用框架内建机制和社区稳定库，仅在确有必要时自定义
3. 兼容性优先 —— 接口变更时保持向后兼容（字段添加不删除、可选参数扩展）
4. 不假设运行环境 —— 所有路径引用使用相对路径，配置使用环境变量 + 默认值