第 15 章：编程开发场景——从零到上线，Codex 全包

终于到了最核心的部分。

前面几章你学会了 Skills、插件、记忆——现在，我们把它们都用起来，看 Codex 如何贯穿一个项目的完整开发周期：从搭项目骨架，到写代码、调 Bug、审代码、写测试、出文档。

你不是一个人在写代码。你的旁边坐着一个永不疲倦的结对编程搭档。

---

15.1 从零搭项目

场景：你想建一个「待办事项」Web 应用

大部分人的路径：搜教程 → 找模板 → 手动创建 → 配环境 → 装依赖……搞完已经累了。

Codex 的路径：一句话搞定。

第一步：一句话起项目

codex -p "帮我创建一个 Todo 应用，使用 React + TypeScript + Tailwind CSS，
         后端用 FastAPI + SQLite，项目名就叫 my-todo"

Codex 会：

1. 创建 my-todo/ 目录，含 frontend/ 和 backend/
2. 前端：create-vite + TypeScript + Tailwind 配置
3. 后端：FastAPI 项目骨架 + SQLite 配置
4. 安装所有依赖
5. 初始化 Git 仓库
6. 生成 README.md 说明项目结构

第二步：生成数据模型

你：帮我建 Todo 的数据模型，包含：
    - id (自增)
    - title (必填)
    - description (可选)
    - completed (布尔，默认 false)
    - created_at (时间戳)
    用 SQLAlchemy + Pydantic

Codex 会生成：

# backend/models/todo.py
from sqlalchemy import Column, Integer, String, Boolean, DateTime
from sqlalchemy.sql import func
from database import Base

class Todo(Base):
    __tablename__ = "todos"
    
    id = Column(Integer, primary_key=True, index=True)
    title = Column(String, nullable=False)
    description = Column(String, nullable=True)
    completed = Column(Boolean, default=False)
    created_at = Column(DateTime(timezone=True), server_default=func.now())

以及对应的 Pydantic schema。

第三步：生成 API 路由

你：帮我生成 CRUD API，支持：
    - GET /todos - 获取所有 todo
    - POST /todos - 创建新 todo
    - PUT /todos/{id} - 更新 todo
    - DELETE /todos/{id} - 删除 todo

第四步：生成前端页面

你：帮我生成一个 Todo 列表页面：
    - 顶部有输入框 + 添加按钮
    - 列表显示所有 todo，可勾选完成状态
    - 每条右边有一个删除按钮
    - 用 Tailwind CSS 美化，加上一些动画效果

第五步：运行项目

你：帮我检查一下项目能不能跑起来

Codex 会启动前后端，检查是否有报错，修复排查到的问题。

💡 从零到跑通，全程大概 15-20 分钟。正常手动做至少要 2 小时起步。

---

15.2 调 Bug

写代码难免出 Bug。Codex 在调试方面的能力相当强大——它不仅能帮你找 Bug，还能帮你理解为什么出 Bug。

场景 1：你遇到了一个报错

你：运行项目时报了这个错：
    ModuleNotFoundError: No module named 'fastapi'

Codex 会做这几步：

1. 分析错误类型（导入错误）
2. 检查你的环境（是否在虚拟环境里？）
3. 提供解决方案和解释

输出示例：

🔍 问题分析
━━━━━━━━━━━━━━━━━━━━━
错误类型：导入错误
原因：你在系统全局环境运行，但 FastAPI 装在虚拟环境里

✅ 解决方案

方案 A（推荐）：激活虚拟环境
  source backend/venv/bin/activate
  python main.py

方案 B：重新安装依赖
  pip install fastapi uvicorn

💡 最好的方式：建议在 backend/ 目录加一个 Makefile，
    用 make run 自动激活环境并启动

场景 2：逻辑 Bug（更难找的）

你：我的 Todo 应用，点击「完成」按钮后，
    页面刷新了但状态没有持久化。
    应该是我前端的代码有问题。
    帮我看一下。

Codex 会读取相关代码，分析问题：

🔍 问题分析
━━━━━━━━━━━━━━━━━━━━━
检查点 1：API 请求
  ✅ PUT 请求正常发送
  
检查点 2：后端处理
  ✅ 后端正确更新了数据库

检查点 3：响应处理 ← 问题在这里！
  ❌ 前端更新状态的代码：
     setTodos(todos.map(...)) 
     但是用的是旧的 todos 状态，导致状态覆盖！
  
✅ 修复方案：
    改用函数式更新：
    setTodos(prev => prev.map(todo =>
      todo.id === id ? { ...todo, completed: !todo.completed } : todo
    ))

调试小技巧

# 让 Codex 逐行看代码
你：帮我把这个函数逐行解释一遍，看看哪里可能出问题

# 让 Codex 模拟运行
你：帮我模拟运行一遍这个函数，输入是 users = [...]
    告诉我每步的变量值变化

# 让 Codex 加日志
你：帮我在这个文件里加上调试日志，
    打印出关键变量的值，方便定位 Bug

💡 最佳实践：给 Codex 提供错误信息和相关代码。越完整，诊断越准。不要说「我的代码出问题了」，要说「第 23 行报错 TypeError: xxx is not a function，以下是相关代码……」。

---

15.3 代码审查和重构

自动代码审查

# 审查整个项目
codex -p "帮我审查 src/ 目录下的所有 Python 文件"

# 或只审查当前文件
codex -p "审查这个文件，重点检查：1）性能问题 2）安全性 3）代码可读性"

审查报告示例：

📋 代码审查报告 - auth.py
━━━━━━━━━━━━━━━━━━━━━━━━━━⭐⭐⭐ (75/100)

🟢 安全
  ✅ 密码用 bcrypt 加密 —— 良好
  ✅ Token 使用了 JWT，验证流程正确
  ⚠️ 第 45 行：错误信息太详细，建议改成泛化消息
     防止攻击者获取信息

🟡 性能
  ✅ 查询用了索引
  ⚠️ 第 78 行：users = User.query.all() 在大型项目里
     会一次性加载全部用户，建议分页或懒加载

🔴 可维护性
  ✅ 函数命名清晰
  ❌ 第 120-180 行：一个函数做了 3 件事（验证、鉴权、
     日志），建议拆分成 3 个独立的函数
  ⚠️ 缺少类型注解（type hints），可读性不够

智能重构

你：帮我把这个函数重构一下，
    它太长了，而且做了太多事情。
    我想拆成几个小函数。

重构前（一个 150 行的函数）：

def process_order(user_id, items, payment_info, shipping_address):
    # 验证用户
    # 检查库存
    # 计算价格
    # 处理支付
    # 创建订单
    # 发送邮件
    # 更新库存
    # 返回结果

重构后（Codex 帮你拆开）：

def process_order(user_id, items, payment_info, shipping_address):
    user = validate_user(user_id)
    validate_stock(items)
    total = calculate_total(items)
    payment_result = process_payment(payment_info, total)
    order = create_order(user, items, total, shipping_address)
    send_confirmation_email(user.email, order)
    update_inventory(items)
    return order

# 每个子函数功能单一，可测试，可复用

代码规范统一

你：帮我确保整个项目的代码风格一致：
    - 统一用双引号
    - 函数之间空两行
    - import 按标准库 / 三方库 / 本地库分组
    - 所有函数加类型注解

---

15.4 生成文档和测试

优秀的程序员写可用代码，卓越的程序员写有文档和有测试的代码。Codex 在这方面简直是神器。

生成文档

行内注释

你：帮我给 utils.py 里的所有函数加上 docstring，
    用 Google 风格的格式

之前：

def calculate_discount(price, coupon):
    if coupon.percent:
        return price * (1 - coupon.percent / 100)
    return price - coupon.amount

之后：

def calculate_discount(price: float, coupon: Coupon) -> float:
    """根据优惠券计算折后价格。

    Args:
        price: 原价，单位为元
        coupon: 优惠券对象

    Returns:
        折后价格，单位为元

    Examples:
        >>> calculate_discount(100, Coupon(percent=20))
        80.0
        >>> calculate_discount(100, Coupon(amount=30))
        70.0
    """
    if coupon.percent:
        return price * (1 - coupon.percent / 100)
    return price - coupon.amount

项目级文档

你：帮我的项目生成 README.md，
    包含：
    - 项目简介
    - 技术栈
    - 安装和运行步骤
    - API 文档（自动从代码里提取）
    - 项目结构说明

你：帮我生成 API 文档（Markdown 格式），
    包含所有路由的说明、请求参数、返回示例。
    从代码里自动提取信息。

生成测试

这是 Codex 最受欢迎的能力之一——帮你写测试代码。

你：帮我对 models/todo.py 生成单元测试，
    覆盖所有 CRUD 操作，包括：
    - 正常流程
    - 边界情况（空标题、长标题）
    - 异常处理

输出：

# tests/test_todo.py
import pytest
from models.todo import Todo

def test_create_todo():
    """测试创建 Todo 的基本功能"""
    todo = Todo(title="测试任务")
    assert todo.title == "测试任务"
    assert todo.completed == False
    assert todo.created_at is not None

def test_create_todo_with_description():
    """测试创建含描述的 Todo"""
    todo = Todo(title="测试", description="这是一个测试")
    assert todo.description == "这是一个测试"

def test_todo_string_representation():
    """测试字符串表示"""
    todo = Todo(title="Hello")
    assert str(todo) == "<Todo(id=None, title='Hello', completed=False)>"

def test_todo_defaults():
    """测试默认值"""
    todo = Todo(title="测试")
    assert todo.completed == False  # 默认为未完成

def test_todo_can_be_completed():
    """测试标记为完成"""
    todo = Todo(title="测试")
    todo.completed = True
    assert todo.completed == True
    
def test_empty_title():
    """测试空标题（边界情况）"""
    with pytest.raises(ValueError):
        Todo(title="")

你：帮我生成测试覆盖率报告

你：帮我把现有的测试都跑一遍，
    如果有失败的我来看

测试的最佳实践

你：帮我写测试时，遵循这些规则：
    1. 每个测试函数只测一个功能
    2. 用清晰的测试命名（test_功能_场景）
    3. 每个测试都有 assert
    4. 不要 mock 不需要的东西

---

本章小结

阶段	Codex 能帮你	省多少时间
搭项目	骨架生成、环境配置、依赖安装	2h → 20min
写代码	生成模型、API、页面	不同场景
调 Bug	分析错误、定位问题、给出修复	减少 70% 调试时间
审代码	扫描安全问题、风格检查、结构优化	即时
写测试	自动生成单元测试、覆盖率报告	1h → 5min
写文档	docstring、README、API 文档	1h → 2min

下一章——真正的「自动化」。把 Codex 变成你的自动化工头，处理数据、定时报告、DevOps 一条龙。

---