HelloMeng
← Back to 文字
AI 应用开发课程 · 月份 1 · 综合项目：研发助手

FastAPI 入口实现

Published2025.10.05 Words 1,405 Reading ~ 5 min

本文来自《AI 应用开发课程》月份 1 课程文档，已整理为网站文章版本。

学习目标

学完本节后，你应当能够：

  • 在综合项目中接上 FastAPI 入口。
  • 复用 CLI 已使用的核心服务层。
  • 让项目具备最小服务化能力。

前置知识

  • 已完成 CLI 入口
  • 已完成 FastAPI 基础模块

1. 为什么项目还要有 API

CLI 适合本地使用，API 则让项目具备：

  • 被其他系统调用的可能
  • 被前端接入的可能
  • 被录屏展示的更强工程感

2. 本项目推荐接口

  • GET /health
  • POST /chat
  • POST /tools/run

如果你的主功能非常明确，也可以额外加：

  • POST /assist/todo
  • POST /assist/commit-message

但前提是这些接口仍然调用同一套核心 service。

3. 入口复用原则

以下两句必须成立：

  • CLI 调用 service
  • FastAPI 调用同一个 service

只要出现“两边各写一套逻辑”，就说明设计失败。

4. 最小服务启动说明

uv run uvicorn app.main:app --reload

建议你在 README 中明确给出：

  • 安装依赖
  • 配置 .env
  • 启动服务
  • 测试接口

5. 实操任务

  1. 给综合项目接入 FastAPI
  2. 接上 /health
  3. 选择一个核心功能暴露为 API
  4. 用 /docs 手动验证

6. 自测题

  1. 为什么项目既要有 CLI，又要有 API？
  2. 为什么“先做 CLI，再接 API”通常更顺？
  3. 如果 API 和 CLI 输出略有不同，哪一层应该吸收差异？

7. 验收标准

  • 服务可启动
  • 至少一个核心功能可通过 API 使用
  • API 与 CLI 共用业务层

8. 本章与前文关系

CLI 已经把核心业务跑通了，现在把它接到 FastAPI 上，难度会显著低于一开始就从 API 写起。

这也正是月份 1 在综合项目里的一个重要教学顺序：

  • 先把业务做清楚
  • 再把协议接上去

9. 本章在研发助手项目中的位置

FastAPI 入口的价值有三个：

  • 对外暴露服务能力
  • 方便用 /docs 展示
  • 为后续月份接入前端或更多服务化能力做准备

10. 一个更完整的 FastAPI 接入示例

app/main.py

"""研发助手 FastAPI 应用入口。"""

from fastapi import FastAPI

from app.api.routes import router


app = FastAPI(title="rd-assistant")
app.include_router(router)

app/api/routes.py

"""研发助手 API 路由。"""

from __future__ import annotations

from fastapi import APIRouter

from app.clients.llm_client import LLMClient
from app.models import ChatRequest, ChatResponse
from app.services.chat_service import ChatService


router = APIRouter()

chat_service = ChatService(llm_client=LLMClient())


@router.get("/health")
async def health() -> dict[str, str]:
    return {"status": "ok"}


@router.post("/chat", response_model=ChatResponse)
async def chat(request: ChatRequest) -> ChatResponse:
    return await chat_service.chat(request)

11. 为什么这里几乎是在“复用”而不是“重写”

因为月份 1 设计得足够清晰的话，FastAPI 接入本质上只是：

  • 把 HTTP 请求转成 ChatRequest
  • 把 ChatService 的输出转成 HTTP 响应

如果你发现这里要重写大量逻辑，通常说明前面的 service 边界没有打好。

12. 调试与排错：本章最常见问题

问题一：API 和 CLI 行为不一致

这通常意味着两边没有复用同一个 service。

问题二：FastAPI 路由里重新拼了一套业务逻辑

这会让项目后续维护成本翻倍。

问题三：README 里无法同时说明 CLI 和 API 用法

这往往暴露的是项目结构或入口边界没有整理好。

13. 本章完成后你应该具备的能力

完成本章后，你应当做到：

  1. 能为综合项目提供 FastAPI 入口。
  2. 能保证它复用 CLI 已用的核心业务逻辑。
  3. 能理解“入口多样化，业务层统一”的项目结构。

14. 从本章过渡到下一章的桥接说明

接下来进入 04-日志-成本-README完善.md。

因为项目主链路已经都接起来了，下一步就是让它从“能跑”升级为“能演示、能解释、能维护”。这一步主要靠日志、调用记录和可读 README 来完成。

15. 为什么这里强调“复用”，而不是“二次开发”

很多项目在新增 API 时，表面上只是“多加一个入口”，实际上却变成了：

  • 再写一遍 prompt 组装
  • 再写一遍 service 逻辑
  • 再写一遍错误处理

这种做法短期看似省事，长期一定会失控。月份 1 特别强调 FastAPI 入口要像“协议适配器”，而不是另一套应用。

16. 一个最小但健康的验收思路

你可以用下面这组问题检查自己的 FastAPI 入口是否健康：

  1. 如果 CLI 的主逻辑改了，API 会不会自动获得同样变化？
  2. 如果我要补日志，是在 service 层补一次，还是 API 和 CLI 各补一次？
  3. 如果后续接前端，API 层是否已经有足够清晰的 schema？

只要其中任意一个问题的答案让你感觉“需要改两遍”，就说明复用边界还不够好。

17. 本章在面试或演示中的表达重点

当你展示这一部分时，最值得强调的是：

  • FastAPI 入口并不是另起一套实现
  • 它复用了月份 1 前面已经形成的模型和 service
  • 这让项目具备了继续扩展的可能

这会比单纯展示“我会起一个接口”更有含金量。

18. 一个最小的 API 演示顺序

为了让展示更流畅，建议你固定按这个顺序演示：

  1. 启动服务
  2. 打开 /health
  3. 打开 /docs
  4. 调用 /chat
  5. 强调该接口背后复用的是和 CLI 同一套业务逻辑

这会让观众快速建立“服务真的可用，而且结构是清楚的”这一印象。

✦ Fin ✦