09-实战：opencode Python Web API 开发

09-实战Python Web API 开发使用 OpenCode 完成 FastAPI Web API 项目的完整开发从初始化到部署。一、项目概述1.1 项目信息项目名称: OpenCode Todo API技术栈: FastAPI SQLAlchemy Pydantic PostgreSQL pytest功能: 用户认证、任务管理、标签管理目标: 演示 OpenCode 的核心功能1.2 功能需求模块功能用户认证注册、登录、JWT Token任务管理CRUD、状态管理、优先级标签管理创建、关联任务搜索过滤全文搜索、多条件过滤二、项目初始化2.1 创建项目结构初始化 FastAPI 项目 opencode-todo-api包含 - 标准项目目录结构 - Python 虚拟环境配置 - Docker 配置 - CI/CD 配置 - 开发环境配置生成结构opencode-todo-api/ ├── app/ │ ├── __init__.py │ ├── main.py # FastAPI 应用入口 │ ├── config.py # 配置管理 │ ├── database.py # 数据库连接 │ ├── models/ # SQLAlchemy 模型 │ ├── schemas/ # Pydantic 模型 │ ├── routers/ # API 路由 │ ├── services/ # 业务逻辑 │ └── utils/ # 工具函数 ├── tests/ # 测试代码 ├── migrations/ # 数据库迁移 ├── docs/ # 文档 ├── requirements.txt # 依赖 ├── Dockerfile # 容器配置 ├── docker-compose.yml # 本地开发环境 └── README.md # 项目说明2.2 配置开发环境配置开发环境1. 创建 .env 文件2. 配置 PostgreSQL 连接3. 设置 JWT 密钥4. 配置日志生成的.env# Database DATABASE_URLpostgresql://user:passwordlocalhost:5432/todo_db # JWT JWT_SECRET_KEYyour-secret-key-here JWT_ALGORITHMHS256 ACCESS_TOKEN_EXPIRE_MINUTES30 # App APP_NAMEOpenCode Todo API DEBUGtrue三、数据库设计3.1 生成模型创建以下 SQLAlchemy 数据模型1. User 模型字段包括 id, username, email, password_hash, is_active, created_at与 Todo 一对多关系2. Todo 模型字段包括 id, title, description, status, priority, user_id, created_at, updated_at与 User 多对一、与 Tag 多对多状态有 pending/in_progress/completed优先级有 low/medium/high3. Tag 模型字段包括 id, name, color, user_id与 User 多对一、与 Todo 多对多4. TodoTag 关联表用于 Todo 和 Tag 的多对多关系生成的app/models/user.pyfromsqlalchemyimportColumn,Integer,String,Boolean,DateTimefromsqlalchemy.ormimportrelationshipfromdatetimeimportdatetimefromapp.databaseimportBaseclassUser(Base):__tablename__usersidColumn(Integer,primary_keyTrue,indexTrue)usernameColumn(String(50),uniqueTrue,indexTrue,nullableFalse)emailColumn(String(255),uniqueTrue,indexTrue,nullableFalse)password_hashColumn(String(255),nullableFalse)is_activeColumn(Boolean,defaultTrue)created_atColumn(DateTime,defaultdatetime.utcnow)# 关系todosrelationship(Todo,back_populatesuser)tagsrelationship(Tag,back_populatesuser)3.2 创建迁移脚本生成 Alembic 迁移配置和初始迁移脚本四、API 开发4.1 用户认证模块创建认证模块1. 密码哈希工具2. JWT Token 生成和验证3. 登录路由4. 注册路由5. 获取当前用户依赖生成的代码# app/utils/auth.pyfromdatetimeimportdatetime,timedeltafromjoseimportJWTError,jwtfrompasslib.contextimportCryptContext SECRET_KEYyour-secret-keyALGORITHMHS256ACCESS_TOKEN_EXPIRE_MINUTES30pwd_contextCryptContext(schemes[bcrypt],deprecatedauto)defverify_password(plain_password,hashed_password):returnpwd_context.verify(plain_password,hashed_password)defget_password_hash(password):returnpwd_context.hash(password)defcreate_access_token(data:dict):to_encodedata.copy()expiredatetime.utcnow()timedelta(minutesACCESS_TOKEN_EXPIRE_MINUTES)to_encode.update({exp:expire})returnjwt.encode(to_encode,SECRET_KEY,algorithmALGORITHM)4.2 并行生成 CRUD 路由创建以下 API 路由模块1. Auth 路由POST /auth/register, POST /auth/login, POST /auth/refresh2. Users 路由GET /users/me, PUT /users/me3. Todos 路由GET /todos(支持过滤、分页), POST /todos, GET /todos/{id}, PUT /todos/{id}, DELETE /todos/{id}, PATCH /todos/{id}/status4. Tags 路由GET /tags, POST /tags, PUT /tags/{id}, DELETE /tags/{id}生成的app/routers/todos.pyfromfastapiimportAPIRouter,Depends,HTTPException,Query,statusfromsqlalchemy.ormimportSessionfromtypingimportList,Optionalfromapp.databaseimportget_dbfromapp.modelsimportTodo,Userfromapp.schemasimportTodoCreate,TodoUpdate,TodoResponsefromapp.routers.authimportget_current_user routerAPIRouter(prefix/todos,tags[todos])router.get(/,response_modelList[TodoResponse])deflist_todos(status:Optional[str]None,priority:Optional[str]None,tag_id:Optional[int]None,search:Optional[str]None,skip:intQuery(0,ge0),limit:intQuery(100,ge1,le1000),db:SessionDepends(get_db),current_user:UserDepends(get_current_user)):querydb.query(Todo).filter(Todo.user_idcurrent_user.id)ifstatus:queryquery.filter(Todo.statusstatus)ifpriority:queryquery.filter(Todo.prioritypriority)ifsearch:queryquery.filter((Todo.title.ilike(f%{search}%))|(Todo.description.ilike(f%{search}%)))todosquery.offset(skip).limit(limit).all()returntodosrouter.post(/,response_modelTodoResponse,status_codestatus.HTTP_201_CREATED)defcreate_todo(todo:TodoCreate,db:SessionDepends(get_db),current_user:UserDepends(get_current_user)):db_todoTodo(**todo.dict(),user_idcurrent_user.id)db.add(db_todo)db.commit()db.refresh(db_todo)returndb_todo五、测试开发5.1 生成测试基础设施生成测试基础设施1. conftest.py - fixtures2. factories.py - 测试数据工厂3. test_client 配置5.2 并行生成测试为以下模块生成完整的 pytest 测试1. 认证模块测试test_register_success, test_register_duplicate, test_login_success, test_login_wrong_password, test_token_refresh2. Users API 测试test_get_current_user, test_update_user3. Todos API 测试test_create_todo, test_list_todos, test_list_todos_with_filters, test_get_todo, test_update_todo, test_delete_todo, test_todo_not_found4. Tags API 测试test_create_tag, test_list_tags, test_update_tag, test_delete_tag5.3 运行测试运行所有测试并生成报告 输出 pytest tests/-v--covapp --cov-reportterm-missing 结果testsession startsplatform linux -- Python3.9.0 plugins: cov-4.0.0 tests/test_auth.py.........[30%]tests/test_users.py....[40%]tests/test_todos.py..........[75%]tests/test_tags.py.......[100%]---------- coverage: platform linux ---------- Name Stmts Miss Cover Missing ------------------------------------------------------- app/__init__.py00100% app/main.py200100% app/routers/auth.py45393%78-80 app/routers/todos.py60592%45-49 app/routers/tags.py40295%55-56 ------------------------------------------------------- TOTAL4052095%35passedin12.34s六、代码审查与优化6.1 批量代码审查并行审查代码 Task1: 审查 Models - SQLAlchemy 使用规范 - 关系定义检查 - 索引优化 Task2: 审查 Routers - 错误处理完整性 - 输入验证 - 权限控制 Task3: 审查 Services - 业务逻辑清晰度 - 异常处理 - 性能优化 Task4: 安全审查 - SQL 注入检查 - JWT 安全性 - 输入消毒6.2 应用优化建议根据审查结果优化代码1. 添加数据库连接池配置2. 优化查询解决 N1 问题3. 添加缓存层4. 完善错误处理七、文档生成7.1 API 文档生成 API 文档 - OpenAPI 规范 - 请求/响应示例 - 错误码说明FastAPI 自动生成Swagger UI:http://localhost:8000/docsReDoc:http://localhost:8000/redoc7.2 项目文档生成 README.md - 项目简介 - 安装说明 - 使用指南 - API 文档链接 - 贡献指南八、部署准备8.1 Docker 配置生成 Docker 配置1. Dockerfile 优化2.docker-compose生产配置3. 多阶段构建生成的DockerfileFROM python:3.9-slim as builder WORKDIR /app COPY requirements.txt . RUN pip install --user -r requirements.txt FROM python:3.9-slim WORKDIR /app COPY --frombuilder /root/.local /root/.local COPY ./app ./app ENV PATH/root/.local/bin:$PATH ENV PYTHONPATH/app EXPOSE 8000 CMD [uvicorn, app.main:app, --host, 0.0.0.0, --port, 8000]8.2 CI/CD 配置生成 GitHub Actions 配置 - 代码质量检查 - 测试运行 - Docker 构建 - 自动部署九、功能演示9.1 使用 MCP 测试 API# 添加 Browser MCP 服务器用于 Web 测试使用opencode mcpaddbrowserserver-url添加浏览器 MCP 服务器# 启动应用在终端运行 uvicorn app.main:app--reload# 测试 API打开 http://localhost:8000/docs测试注册端点 POST /auth/register测试登录端点 POST /auth/login测试创建 Todo POST /todos截图保存测试结果9.2 完整开发流程演示# 会话1: 项目初始化初始化 FastAPI 项目配置开发环境# 会话2: 数据库设计设计模型创建迁移# 会话3: 认证模块实现 JWT 认证# 会话4: CRUD 开发使用自然语言描述需求AI 会逐步生成各模块代码# 会话5: 测试生成测试运行并修复# 会话6: 审查代码审查性能优化# 会话7: 部署Docker 配置部署到服务器十、项目总结10.1 OpenCode 功能展示功能应用场景效果自然语言指令用自然语言描述需求生成代码快速原型开发MCP通过 MCP 服务器扩展能力如浏览器测试可视化验证多轮对话逐步迭代完善代码持续优化上下文理解基于项目结构生成一致的代码代码一致性10.2 代码统计项目统计 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 总文件数: 25 Python 代码: 2000 行 测试代码: 800 行 测试覆盖率: 95% API 端点: 15 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━十一、下一步完成实战项目后建议学习10-多模型配置指南.md - 配置多个大模型11-项目规划测试代码审查实战.md - 全流程管理文档版本: 1.0 | 建议学习时长: 90分钟