Community编程与开发github.com

fastapi-api-builder

从头到尾的指南,用于使用 Python 和 FastAPI 设计、构建、测试、打包和部署 REST API。每当用户想要创建、设计、构建、暴露或部署 API、后端、Web 服务、端点、Webhook,或将脚本/流程转换为可由 RPA 机器人、Automation Anywhere、应用程序或前端调用的服务时,均可使用此技能,即使未提及 FastAPI 或部署。

fastapi-api-builder 是什么?

这是一个全面的 AI 助手技能,旨在引导用户通过六个阶段(理解 → 设计 → 构建 → 测试 → 打包 → 部署)完成 FastAPI REST API 的端到端开发。它通过最少的关键问题(如目的、持久化、消费者和目的地)主动收集需求,并根据需要假设合理的默认值(如 FastAPI、API 密钥、pytest、Docker)。该技能可生成代码、运行测试、创建 Dockerfile,并提供跨平台部署指导,包括 VPS(基于 Docker)、PaaS(如 Render、Railway)和云(Cloud Run、App Runner)。它强调实际工作流程,要求用户授权执行实际部署,并避免因过时文档而提供误导性说明。该技能支持 Claude Code、Cursor 和 Codex 工具,利用架构参考(如 `references/auth.md`)并与 RPA/Automation Anywhere 集成,确保生成的 API 符合行业标准。

兼容平台✓Claude Code~Codex CLI~Cursor
Part ofMobile
npx skills add https://github.com/EstefaniaRojasal-design/Skills/tree/main/fastapi-api-builder

Installed? Explore more 编程与开发 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

使用 FastAPI 构建 API:从设计到部署

指导用户完成六个阶段:理解 → 设计 → 构建 → 测试 → 打包 → 部署。仅询问会改变结果的问题,其余通过声明假设来推断,并无需逐个阶段请求批准即可进行构建。

职责与限制

  • 在可用环境中生成并测试代码。
  • 实际部署由用户在其账户或服务器上执行,因为助手通常无访问权限。提供精确的命令和验证步骤。
  • 如果环境可以访问服务器或平台 CLI(例如 Claude Code),仅在获得用户必要确认后执行操作。
  • 如果无法执行测试或部署,请勿声称已执行。

阶段 1:理解(一轮关键问题)

在编写代码前,明确影响架构的关键点。如果有可点击选项的提问工具(ask_user_input_v0),请使用;否则,列出简要问题列表。最多三到四个问题,跳过已回答的:

  1. 目的与资源: API 的功能是什么?操作哪些实体(例如客户、发票、订单)?需要哪些操作?
  2. 持久化: 无数据库、SQLite(原型)还是 PostgreSQL?
  3. 消费者与访问: 谁调用它(RPA/Automation Anywhere 机器人、Web 应用、其他服务)?应该是公开的还是内部的?这决定了身份验证和部署。
  4. 目标: 如果已知,则直接使用;否则,呈现阶段 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.md
  • references/deploy-paas.md
  • references/deploy-cloud.md

外部平台的命令和屏幕会变化。如果用户指出界面不匹配,请查阅当前文档,而非坚持过时的说明。

最后进行部署后验证:

curl https://<url>/health

打开 /docs,测试带密钥和不带密钥的端点(不带应返回 401),并检查日志。如果失败,请求错误或日志并进行诊断。常见问题:端口错误(应用应监听 $PORT)、缺少环境变量、使用 postgres:// 而非 postgresql://,或 CORS 阻止前端。

最终交付格式

保持简洁有用,包括:

  1. 构建内容及所做的假设。
  2. 本地运行命令。
  3. 所需环境变量。
  4. 端点表。
  5. 所选部署的后续步骤。

避免不必要地重复文件内容。

相关技能