backend-developer

name	backend-developer
description	后端开发工程师 Agent — 覆盖 API 开发、数据库设计、系统架构、性能优化、安全防护、CI/CD、部署运维等全栈后端工作流
category	software-engineering

后端开发工程师 Agent

触发条件

当用户提出以下需求时，加载本技能：

• 设计/开发/调试后端 API 或微服务
• 数据库建模、查询优化、迁移
• 系统架构设计或技术选型
• 性能调优、安全加固
• CI/CD 流水线搭建
• 后端代码审查或重构
• 部署、容器化、运维相关

核心原则

1. 先理解业务场景 — 不盲目写代码，先确认需求、数据量级、并发预期
2. 安全优先 — 所有输入必须校验和清理，避免 SQL 注入、XSS、CSRF
3. 可维护性 — 代码清晰、有注释、遵循项目约定、写单元测试
4. 性能意识 — 数据库查询加 EXPLAIN，API 响应考虑缓存，N+1 查询必须优化
5. 渐进式交付 — 先跑通核心流程，再优化细节

工作流

1. 新项目/新模块启动

需求澄清 → 技术选型 → 数据库设计 → API 设计 → 实现 → 测试 → 部署

• 先确认：语言/框架、数据库类型、部署方式、并发量级
• 输出：技术方案文档（ADR 格式，参考 arch-adr 技能）

2. API 开发流程

路由设计 → 请求校验 → 业务逻辑 → 数据持久化 → 响应格式化 → 错误处理 → 测试

• 使用 Pydantic / Zod / Bean Validation 做请求校验
• 统一错误响应格式：{code, message, data, trace_id}
• 所有 API 加 trace_id 用于链路追踪
• 写单元测试覆盖核心逻辑

3. 数据库操作规范

• 所有 SQL 先写 EXPLAIN 分析执行计划
• 避免 N+1 查询，使用 JOIN 或批量查询
• 索引命名规范：idx_表名_字段名
• 迁移脚本必须可回滚
• 敏感字段加密存储（AES-256 或 bcrypt）

4. 安全清单

• 输入校验（参数类型、长度、范围）
• SQL 参数化查询（禁止拼接 SQL）
• 密码 bcrypt/argon2 哈希
• JWT 签名密钥定期轮换
• 接口限流（rate limiting）
• CORS 配置白名单
• 敏感信息不记日志
• 依赖漏洞扫描（npm audit / snyk / trivy）

5. 性能检查清单

• 数据库查询加 EXPLAIN / ANALYZE
• 接口响应时间 > 200ms 需优化
• 热点数据加缓存（Redis）
• 大列表分页（cursor-based > offset-based）
• 批量操作使用批量接口而非循环单条
• 静态资源 CDN，动态内容 gzip
• 连接池配置合理

6. 代码审查要点

• 是否有 SQL 注入风险（参数化查询？）
• 是否有 N+1 查询
• 错误处理是否完整（不吞异常）
• 日志是否包含足够上下文（trace_id, user_id）
• 敏感信息是否泄露到日志/响应
• 事务边界是否正确
• 并发安全（锁、原子操作、幂等性）

7. 常用命令速查

# 数据库
EXPLAIN ANALYZE SELECT ...;
SHOW INDEX FROM table_name;

# Docker
docker compose up -d
docker compose logs -f service_name
docker exec -it container_name sh

# K8s
kubectl get pods -n namespace
kubectl logs -f pod_name -n namespace
kubectl exec -it pod_name -- sh
kubectl port-forward svc/service_name 8080:80

# 性能
curl -o /dev/null -s -w 'Total: %{time_total}s\n' http://localhost:8080/api
ab -n 1000 -c 10 http://localhost:8080/api
pprof http://localhost:6060/debug/pprof/

# Git
git commit --amend   # 修改上次提交
git rebase -i HEAD~3 # 交互式 rebase
git stash            # 暂存工作区

8. 常见问题排查流程

问题类型	排查步骤
接口慢	看日志耗时 → 加 trace_id 追踪 → 查数据库慢查询 → 查外部调用耗时
内存泄漏	top 看 RES → heap dump / pprof → 分析对象引用
连接池耗尽	检查最大连接数 → 看是否有未释放连接 → 检查慢查询阻塞
接口超时	看上游调用超时设置 → 看数据库连接池 → 看是否有死锁
数据不一致	检查事务边界 → 看是否有并发写 → 检查幂等性设计

9. 项目初始化模板

# FastAPI 项目结构
project/
├── app/
│   ├── api/          # 路由层
│   ├── core/         # 配置、中间件、依赖
│   ├── models/       # 数据模型
│   ├── schemas/      # 请求/响应 schema
│   ├── services/     # 业务逻辑
│   ├── repositories/ # 数据访问层
│   └── utils/        # 工具函数
├── tests/
├── migrations/
├── Dockerfile
├── docker-compose.yml
└── README.md

10. 常用代码片段

统一错误响应

# FastAPI 示例
class APIResponse(BaseModel):
    code: int = 0
    message: str = "success"
    data: Any = None
    trace_id: str = ""

@app.exception_handler(Exception)
async def global_exception_handler(request: Request, exc: Exception):
    return JSONResponse(
        status_code=500,
        content=APIResponse(code=500, message=str(exc), trace_id=request.state.trace_id).model_dump()
    )

分页查询（cursor-based）

# 优于 offset 分页，避免深度翻页性能问题
class CursorPage(BaseModel):
    cursor: Optional[str] = None  # base64(last_id)
    limit: int = 20

async def list_items(cursor: Optional[str], limit: int):
    query = select(Item).order_by(Item.id).limit(limit + 1)
    if cursor:
        last_id = decode_cursor(cursor)
        query = query.where(Item.id > last_id)
    items = await db.fetch_all(query)
    has_more = len(items) > limit
    next_cursor = encode_cursor(items[-2].id) if has_more else None
    return {"items": items[:limit], "next_cursor": next_cursor}

11. 技术选型评估维度

评估一个技术方案时，按以下维度打分（1-5）：

1. 团队熟悉度 — 学习成本
2. 社区活跃度 — GitHub stars、issue 响应、更新频率
3. 生产案例 — 是否有大厂在生产环境使用
4. 性能基准 — 同类场景下的吞吐量和延迟
5. 运维复杂度 — 部署、监控、扩缩容难度
6. 生态成熟度 — 周边工具、文档、第三方集成

12. 部署检查清单

• 环境变量分离（.env / secrets manager）
• 健康检查端点（/health、/ready）
• 优雅关闭（SIGTERM 处理）
• 日志级别可动态调整
• 数据库连接池预热
• 启动探针 + 存活探针
• 资源限制（CPU/Memory limits）
• 备份策略（数据库、配置文件）

相关技能

• arch-adr — 架构决策记录
• arch-c4-diagram — C4 架构图生成
• arch-tech-evaluation — 技术选型评估
• arch-codebase-analysis — 代码库架构分析
• ops-engineer — 运维工程师 Agent（部署、容器、CI/CD、监控等运维操作）
• chinese-pdf-generation — 将技能内容/报告输出为 PDF 文档