09-实战：Claude code Python Web API 开发

09-实战Python Web API 开发通过开发一个完整的 FastAPI Todo API综合运用 Claude Code 的 MCP、Sub Agent、Hooks、Skills 等核心功能。一、项目概述1.1 项目信息项目名称: FastAPI Todo API项目地址: github.com/example/fastapi-todo-api技术栈: FastAPI SQLAlchemy Pydantic PostgreSQL pytest项目类型: RESTful Web API1.2 功能特性FastAPI Todo API - 任务管理 API 核心功能 - 用户注册/登录 (JWT 认证) - 任务的增删改查 - 任务分类管理 - 任务优先级设置 - 任务完成状态追踪1.3 项目结构fastapi-todo-api/ ├── app/ │ ├── __init__.py │ ├── main.py # FastAPI 应用入口 │ ├── config.py # 配置管理 │ ├── models/ # SQLAlchemy 模型 │ │ ├── __init__.py │ │ ├── user.py │ │ ├── todo.py │ │ └── category.py │ ├── schemas/ # Pydantic 模型 │ │ ├── __init__.py │ │ ├── user.py │ │ ├── todo.py │ │ └── category.py │ ├── routers/ # API 路由 │ │ ├── __init__.py │ │ ├── auth.py │ │ ├── todos.py │ │ └── categories.py │ ├── services/ # 业务逻辑 │ │ ├── __init__.py │ │ ├── auth_service.py │ │ ├── todo_service.py │ │ └── category_service.py │ └── utils/ # 工具函数 │ ├── __init__.py │ ├── security.py │ └── validators.py ├── tests/ │ ├── __init__.py │ ├── conftest.py # pytest fixtures │ ├── test_auth.py │ ├── test_todos.py │ └── test_categories.py ├── alembic/ # 数据库迁移 ├── requirements.txt ├── requirements-dev.txt ├── docker-compose.yml ├── Dockerfile ├── CLAUDE.md # Claude Code 配置 ├── .env.example ├── .gitignore └── README.md二、环境准备2.1 初始化项目在 Claude Code 中执行# 创建项目目录mkdirfastapi-todo-apicdfastapi-todo-api# 初始化项目帮我初始化一个 FastAPI 项目包含1. 创建上述目录结构2. 创建基础配置文件3. 创建 requirements.txt4. 创建 README.md5. 初始化 Git 仓库6. 创建 .gitignore Claude 会自动创建完整的项目结构。2.2 配置文件requirements.txt:fastapi0.104.1 uvicorn[standard]0.24.0 sqlalchemy2.0.23 asyncpg0.29.0 alembic1.12.1 pydantic2.5.0 pydantic-settings2.1.0 python-jose[cryptography]3.3.0 passlib[bcrypt]1.7.4 python-multipart0.0.6 pytest7.4.3 pytest-asyncio0.21.1 httpx0.25.2requirements-dev.txt:-r requirements.txt black23.11.0 flake86.1.0 mypy1.7.1 isort5.12.0 pytest-cov4.1.0CLAUDE.md:# CLAUDE.md - FastAPI Todo API 项目配置 ## 项目信息 - **名称**: FastAPI Todo API - **技术栈**: FastAPI SQLAlchemy 2.0 PostgreSQL - **Python版本**: 3.9 ## 开发规范 ### 代码风格 - 使用 Black 格式化行宽 100 - 使用 Flake8 检查max-line-length100 - 所有函数必须添加类型注解 - 使用 Google Style Docstrings ### 架构规范 - 使用 SQLAlchemy 2.0 新语法select(), session.get() - 使用 Pydantic V2 BaseModel - 依赖注入管理数据库会话 - 统一错误处理格式 ### API 规范 - 使用 APIRouter 组织路由 - 响应模型使用 Pydantic - 统一错误响应格式{detail: 错误消息} - 认证使用 JWT Bearer Token ## 常用命令 bash # 启动开发服务器 uvicorn app.main:app --reload --host 0.0.0.0 --port 8000 # 运行测试 pytest tests/ -v --covapp --cov-reportterm-missing # 数据库迁移 alembic revision --autogenerate -m 描述 alembic upgrade head # 代码格式化 black app/ tests/ isort app/ tests/ # 类型检查 mypy app/项目结构app/ ├── main.py # FastAPI 应用 ├── config.py # 配置 ├── models/ # SQLAlchemy 模型 ├── schemas/ # Pydantic 模型 ├── routers/ # API 路由 ├── services/ # 业务逻辑 └── utils/ # 工具函数### 2.3 配置 MCP 服务器 bash 配置 MCP 服务器 1. 添加 Browser MCP 用于测试 API 2. 添加 Context7 MCP 用于查询文档 3. 配置 File System MCP 访问项目文件三、使用 Claude Code 开发3.1 创建数据模型使用 Sub Agent 并行创建请并行创建以下 SQLAlchemy 模型 任务1 - User 模型 创建 app/models/user.py - 字段id, username, email, hashed_password, is_active, created_at - 关系一个用户有多个 Todos - 使用 SQLAlchemy2.0语法 任务2 - Todo 模型 创建 app/models/todo.py - 字段id, title, description, completed, priority, due_date, created_at, updated_at, user_id, category_id - 关系属于 User属于 Category - 优先级low, medium, high, urgent 任务3 - Category 模型 创建 app/models/category.py - 字段id, name, description, user_id - 关系属于 User有多个 Todos 所有模型使用 SQLAlchemy2.0的 DeclarativeBase 使用 Mapped[]类型注解语法。生成的模型代码示例# app/models/user.pyfromdatetimeimportdatetimefromtypingimportList,OptionalfromsqlalchemyimportStringfromsqlalchemy.ormimportMapped,mapped_column,relationshipfromapp.databaseimportBaseclassUser(Base):用户模型__tablename__usersid:Mapped[int]mapped_column(primary_keyTrue)username:Mapped[str]mapped_column(String(50),uniqueTrue,indexTrue)email:Mapped[str]mapped_column(String(100),uniqueTrue,indexTrue)hashed_password:Mapped[str]mapped_column(String(255))is_active:Mapped[bool]mapped_column(defaultTrue)created_at:Mapped[datetime]mapped_column(defaultdatetime.utcnow)# 关系todos:Mapped[List[Todo]]relationship(back_populatesuser)categories:Mapped[List[Category]]relationship(back_populatesuser)3.2 创建 Pydantic Schemas为所有模型创建 Pydantic schemas1. UserCreate, UserResponse, UserLogin2. TodoCreate, TodoUpdate, TodoResponse, TodoList3. CategoryCreate, CategoryResponse 使用 Pydantic V2 语法所有字段添加 Field 约束。示例# app/schemas/todo.pyfromdatetimeimportdate,datetimefromtypingimportOptionalfrompydanticimportBaseModel,FieldclassTodoBase(BaseModel):Todo 基础模型title:strField(...,min_length1,max_length200)description:Optional[str]Field(None,max_length1000)priority:strField(defaultmedium,pattern^(low|medium|high|urgent)$)due_date:Optional[date]NoneclassTodoCreate(TodoBase):创建 Todo 请求category_id:Optional[int]NoneclassTodoUpdate(BaseModel):更新 Todo 请求title:Optional[str]Field(None,min_length1,max_length200)description:Optional[str]Field(None,max_length1000)completed:Optional[bool]Nonepriority:Optional[str]Field(None,pattern^(low|medium|high|urgent)$)due_date:Optional[date]Nonecategory_id:Optional[int]NoneclassTodoResponse(TodoBase):Todo 响应模型id:intcompleted:boolcreated_at:datetime updated_at:datetime user_id:intcategory_id:Optional[int]classConfig:from_attributesTrue3.3 创建 API 路由使用 Skills 规范生成创建 API 路由文件1. app/routers/auth.py - 认证路由登录、注册2. app/routers/todos.py - Todo CRUD3. app/routers/categories.py - 分类管理 使用 fastapi-api Skill 的规范 - 使用 APIRouter - 使用依赖注入 - 添加适当的 tags - 实现完整的错误处理示例路由# app/routers/todos.pyfromtypingimportListfromfastapiimportAPIRouter,Depends,HTTPException,statusfromsqlalchemy.ext.asyncioimportAsyncSessionfromapp.databaseimportget_dbfromapp.models.userimportUserfromapp.schemas.todoimportTodoCreate,TodoResponse,TodoUpdatefromapp.services.authimportget_current_userfromapp.services.todo_serviceimportTodoService routerAPIRouter(prefix/todos,tags[todos])router.get(/,response_modelList[TodoResponse])asyncdeflist_todos(skip:int0,limit:int100,db:AsyncSessionDepends(get_db),current_user:UserDepends(get_current_user))-List[TodoResponse]:获取当前用户的所有 TodoserviceTodoService(db)todosawaitservice.get_user_todos(current_user.id,skip,limit)returntodosrouter.post(/,response_modelTodoResponse,status_codestatus.HTTP_201_CREATED)asyncdefcreate_todo(todo:TodoCreate,db:AsyncSessionDepends(get_db),current_user:UserDepends(get_current_user))-TodoResponse:创建新 TodoserviceTodoService(db)returnawaitservice.create_todo(todo,current_user.id)router.get(/{todo_id},response_modelTodoResponse)asyncdefget_todo(todo_id:int,db:AsyncSessionDepends(get_db),current_user:UserDepends(get_current_user))-TodoResponse:获取指定 TodoserviceTodoService(db)todoawaitservice.get_todo(todo_id,current_user.id)ifnottodo:raiseHTTPException(status_codestatus.HTTP_404_NOT_FOUND,detailTodo not found)returntodorouter.put(/{todo_id},response_modelTodoResponse)asyncdefupdate_todo(todo_id:int,todo_update:TodoUpdate,db:AsyncSessionDepends(get_db),current_user:UserDepends(get_current_user))-TodoResponse:更新 TodoserviceTodoService(db)todoawaitservice.update_todo(todo_id,current_user.id,todo_update)ifnottodo:raiseHTTPException(status_codestatus.HTTP_404_NOT_FOUND,detailTodo not found)returntodorouter.delete(/{todo_id},status_codestatus.HTTP_204_NO_CONTENT)asyncdefdelete_todo(todo_id:int,db:AsyncSessionDepends(get_db),current_user:UserDepends(get_current_user))-None:删除 TodoserviceTodoService(db)successawaitservice.delete_todo(todo_id,current_user.id)ifnotsuccess:raiseHTTPException(status_codestatus.HTTP_404_NOT_FOUND,detailTodo not found)3.4 创建业务逻辑层创建 Service 层1. TodoService - 处理 Todo 业务逻辑2. CategoryService - 处理分类业务逻辑3. AuthService - 处理认证业务逻辑 所有服务类使用依赖注入获取数据库会话。3.5 自动化测试使用自动化 Hooks 生成测试配置自动化测试流程 创建 tests/ 下的测试文件1. conftest.py - 配置 fixtures2. test_auth.py - 认证测试3. test_todos.py - Todo API 测试4. test_categories.py - 分类 API 测试 然后运行测试验证。 Claude 会自动1. 生成测试代码2. 运行 pytest3. 显示测试结果示例测试# tests/test_todos.pyimportpytestfromhttpximportAsyncClientfromsqlalchemy.ext.asyncioimportAsyncSessionfromapp.mainimportappfromapp.models.todoimportTodofromapp.models.userimportUserpytest.fixtureasyncdefauth_headers(async_client:AsyncClient,test_user:User)-dict:获取认证 headersresponseawaitasync_client.post(/api/v1/auth/login,json{username:test_user.username,password:testpassword})tokenresponse.json()[access_token]return{Authorization:fBearer{token}}pytest.mark.asyncioasyncdeftest_create_todo(async_client:AsyncClient,auth_headers:dict,db_session:AsyncSession):测试创建 Todoresponseawaitasync_client.post(/api/v1/todos/,headersauth_headers,json{title:Test Todo,description:Test description,priority:high})assertresponse.status_code201dataresponse.json()assertdata[title]Test Todoassertdata[priority]highassertdata[completed]isFalsepytest.mark.asyncioasyncdeftest_list_todos(async_client:AsyncClient,auth_headers:dict,test_user:User,db_session:AsyncSession):测试获取 Todo 列表# 创建测试数据todo1Todo(titleTodo 1,user_idtest_user.id)todo2Todo(titleTodo 2,user_idtest_user.id)db_session.add_all([todo1,todo2])awaitdb_session.commit()responseawaitasync_client.get(/api/v1/todos/,headersauth_headers)assertresponse.status_code200dataresponse.json()assertlen(data)2四、项目功能总结4.1 使用的 Claude Code 功能功能应用场景Sub Agent并行创建模型、路由、服务MCP Browser测试 API 端点MCP Context7查询 FastAPI/SQLAlchemy 文档Hooks 自动化运行测试、代码检查Skills标准化 API 代码生成自然语言 Git提交代码、创建分支4.2 开发效率对比任务传统方式Claude Code效率提升项目初始化2 小时20 分钟6x模型创建3 小时30 分钟6xAPI 开发4 小时1 小时4x测试编写3 小时30 分钟6x文档编写2 小时20 分钟6x五、下一步学习完成本实战项目后你已经掌握了 Claude Code 的核心功能。建议在自己的项目中应用这些技巧创建更多自定义 Skills探索更多 MCP 服务器与 Cursor 结合使用发挥各自优势