使用 FastAPI 构建 API:从设计到部署
指导用户完成六个阶段:理解 → 设计 → 构建 → 测试 → 打包 → 部署。仅询问会改变结果的问题,其余通过声明假设来推断,并无需逐个阶段请求批准即可进行构建。
职责与限制
- 在可用环境中生成并测试代码。
- 实际部署由用户在其账户或服务器上执行,因为助手通常无访问权限。提供精确的命令和验证步骤。
- 如果环境可以访问服务器或平台 CLI(例如 Claude Code),仅在获得用户必要确认后执行操作。
- 如果无法执行测试或部署,请勿声称已执行。
阶段 1:理解(一轮关键问题)
在编写代码前,明确影响架构的关键点。如果有可点击选项的提问工具(ask_user_input_v0),请使用;否则,列出简要问题列表。最多三到四个问题,跳过已回答的:
- 目的与资源: API 的功能是什么?操作哪些实体(例如客户、发票、订单)?需要哪些操作?
- 持久化: 无数据库、SQLite(原型)还是 PostgreSQL?
- 消费者与访问: 谁调用它(RPA/Automation Anywhere 机器人、Web 应用、其他服务)?应该是公开的还是内部的?这决定了身份验证和部署。
- 目标: 如果已知,则直接使用;否则,呈现阶段 6 的选项,推荐一个但不阻塞构建。
对于其他事项,假设合理的默认值(FastAPI、API 密钥、统一错误格式、pytest、Docker)并在一行中声明。
阶段 2:设计
在构建前,提供紧凑的设计,供用户纠正;如果用户确认或未提出异议,则继续构建:
- 端点表:方法、路由、函数和响应代码。
- 输入/输出模型:字段和验证。
- 选定的身份验证及其理由;如果存在,参考
references/auth.md。
REST 约定:复数名词(/clientes)、HTTP 动词表示动作、201 表示创建、204 表示删除、404 表示不存在、422 表示数据无效、401 表示无凭据。
阶段 3:构建
如果可用,通过脚手架使用经过测试的模板,而非重写:
python <skill-path>/scripts/scaffold.py "<project-name>" --out /home/claude
调整模板以匹配设计:
- 将示例资源
app/routers/items.py和app/schemas.py替换为所需资源。 - 在
app/main.py中使用include_router注册路由器。 - 针对新变量调整
app/config.py和.env.example。 - 如果有数据库,参考(如果存在)
references/database.md。 - 如果需要用户登录,参考(如果存在)
references/auth.md。 - 如果消费者是 Automation Anywhere,参考(如果存在)
references/aa-integration.md并应用其契约:清晰的 HTTP 代码、包含status和有用消息的 JSON。
不要编造不可用的模板文件或参考资料。如果不存在,则显式创建等效解决方案。
分层结构(路由器、模式、配置、安全)便于扩展;Pydantic 在逻辑之前验证数据;全局处理程序返回统一错误,例如 {"status":"error","message":"..."},而不在 500 错误中泄露内部细节。包含 /health 端点用于 Docker、负载均衡器和平台。通过环境变量配置:相同的代码在本地和生产中运行,机密信息不出现在仓库中。
阶段 4:测试
在交付前始终执行测试,并修复错误直到通过,如果环境允许:
cd <project> && pip install -r requirements-dev.txt && python -m pytest -q
为每个新端点添加测试:正常情况、无效数据、资源未找到以及无身份验证(如适用)。如果可能,启动真实服务器(uvicorn app.main:app --port 8000)并使用 curl 验证 /health、带密钥和不带密钥的保护端点以及 /docs。如果某些测试无法执行,解释原因和不足。
阶段 5:打包
- Dockerfile 应以无特权用户身份运行,并监听
$PORT,以便在 Render、Railway、Cloud Run 和 VPS 上工作相同。 .dockerignore和.gitignore应排除.env;检查代码或交付文件中无机密。- 如果可用,将完整项目压缩到
/mnt/user-data/outputs/并使用present_files;否则,以有用形式提供结构和文件,不声称已创建 ZIP。 - 包含简短摘要:如何本地运行、所需环境变量和端点。
生产前检查清单
-
API_KEY(或 JWT)定义为长随机值,并作为平台机密保存。 -
CORS_ORIGINS为显式列表,而非*。 -
ENVIRONMENT=production。 - 持久化数据库并备份;不要在临时磁盘上使用 SQLite。
- 启用 HTTPS;绝不在 HTTP 上暴露 API 密钥。
-
.env不在仓库中。 - 测试通过,
/health响应正常。 - 日志可访问,并在 5xx 错误时发出警报。
阶段 6:部署
如果用户未选择目标,呈现以下比较并根据其情况推荐。如果用户基础设施经验较少,使用 PaaS;如果需要内部网络或完全控制,使用 VPS/自有服务器;如果公司已使用云,使用该云上的托管容器。
| 选项 | 工作量 | 控制 | 典型成本 | 最佳适用场景 |
|---|---|---|---|---|
| VPS 或自有服务器上的 Docker | 中等 | 完全 | 固定且较低 | 内部网络、控制、可预测成本 |
| PaaS(Render、Railway、Fly.io) | 低 | 中等 | 低到中等,按使用量计费 | 快速推出、小团队 |
| 云(Cloud Run、Container Apps、App Runner/ECS) | 中到高 | 高 | 按使用量计费 | 使用云的企业、扩展、合规 |
选择后,仅参考相应的指南(如果存在):
references/deploy-vps-docker.mdreferences/deploy-paas.mdreferences/deploy-cloud.md
外部平台的命令和屏幕会变化。如果用户指出界面不匹配,请查阅当前文档,而非坚持过时的说明。
最后进行部署后验证:
curl https://<url>/health
打开 /docs,测试带密钥和不带密钥的端点(不带应返回 401),并检查日志。如果失败,请求错误或日志并进行诊断。常见问题:端口错误(应用应监听 $PORT)、缺少环境变量、使用 postgres:// 而非 postgresql://,或 CORS 阻止前端。
最终交付格式
保持简洁有用,包括:
- 构建内容及所做的假设。
- 本地运行命令。
- 所需环境变量。
- 端点表。
- 所选部署的后续步骤。
避免不必要地重复文件内容。