🚀 Codex CLI 实战案例：10个真实开发场景手把手教学

📅 更新于 2026年5月 | ✍️ 原创文章，转载请注明出处

本系列共12篇，本文是第4篇

---

📌 目录

1. 场景1：代码重构
2. 场景2：Bug 修复
3. 场景3：单元测试编写
4. 场景4：API 开发
5. 场景5：数据库迁移
6. 场景6：文档生成
7. 场景7：代码审查
8. 场景8：性能优化
9. 场景9：Git 操作
10. 场景10：项目初始化
11. 实战技巧总结
12. 总结

---

1. 场景1：代码重构

🎯 目标

将一个 500 行的"上帝类"重构为符合单一职责的多个类。

📝 原始代码

// UserService.java - 500 行的"上帝类"
@Service
public class UserService {
    // 用户 CRUD
    // 订单处理
    // 支付逻辑
    // 通知发送
    // 报表生成
}

💬 对话过程

第1轮：分析代码

codex

> 请分析 src/main/java/com/example/service/UserService.java 的代码结构，
> 列出它承担了哪些职责，应该如何拆分

Codex 输出：

分析 UserService.java，发现以下职责：

1. 用户管理（CRUD）- 约 150 行
2. 订单处理 - 约 120 行
3. 支付逻辑 - 约 100 行
4. 通知发送 - 约 80 行
5. 报表生成 - 约 50 行

建议拆分为：
- UserService：用户 CRUD
- OrderService：订单处理
- PaymentService：支付逻辑
- NotificationService：通知发送
- ReportService：报表生成

第2轮：执行重构

> 好的，请按照建议拆分，保持原有功能不变，
> 每个类添加必要的依赖注入，运行测试确保没有破坏

第3轮：检查结果

> /run mvn test

> 所有测试通过，请提交代码
> /git add .
> /git commit -m "refactor: split UserService into 5 single-responsibility services"

✅ 结果

• 500 行 → 5 个类，平均每个 100 行
• 代码可读性提升
• 测试覆盖率不变
• 所有测试通过

---

2. 场景2：Bug 修复

🎯 目标

修复一个间歇性出现的 NullPointerException。

📝 错误信息

java.lang.NullPointerException: Cannot invoke "String.length()" because "username" is null
    at com.example.service.UserService.validateUsername(UserService.java:45)
    at com.example.controller.UserController.createUser(UserController.java:32)

💬 对话过程

第1轮：定位问题

codex

> 有个 NPE 错误：
> Cannot invoke "String.length()" because "username" is null
> at UserService.validateUsername(UserService.java:45)
> 
> 请找到这个方法，分析为什么会空指针，给出修复方案

第2轮：分析根因

> /read src/main/java/com/example/service/UserService.java

> 为什么会是 null？上游调用链是什么？

Codex 分析：

根因分析：

1. validateUsername() 第 45 行调用 username.length()
2. username 来自 UserDTO.getUsername()
3. 前端可能发送了 {"username": null} 或 {"username": ""}
4. Controller 没有做空值校验

修复方案：
1. 添加 @NotNull 注解到 UserDTO.username
2. validateUsername() 添加空值检查
3. Controller 添加 @Valid 注解

第3轮：执行修复

> 按照方案修复，并添加单元测试覆盖这个边界情况

第4轮：验证修复

> /run mvn test

> 测试通过，再手动验证下边界情况
> /run curl -X POST http://localhost:8080/api/users -d '{"username": null}'

✅ 结果

• 问题定位：2 分钟
• 修复方案：3 分钟
• 代码修改：1 分钟
• 测试验证：2 分钟
• 总计：8 分钟（传统方式可能需要 30+ 分钟）

---

3. 场景3：单元测试编写

🎯 目标

为一个没有测试的 Service 类补充单元测试。

📝 原始代码

// OrderService.java - 没有测试
@Service
public class OrderService {
    public Order createOrder(User user, List<Product> products) {
        // 验证用户
        // 计算总价
        // 应用优惠
        // 创建订单
        // 发送通知
    }
    
    public Order cancelOrder(Long orderId) {
        // 验证订单状态
        // 退款
        // 更新状态
        // 发送通知
    }
}

💬 对话过程

第1轮：生成测试框架

codex

> 为 src/main/java/com/example/service/OrderService.java 编写单元测试
> 
> 要求：
> 1. 使用 JUnit 5 + Mockito
> 2. 覆盖所有公开方法
> 3. 测试正常流程和异常流程
> 4. 测试边界条件
> 5. Mock 所有外部依赖

第2轮：补充测试用例

> 还需要测试以下场景：
> 1. 产品列表为空
> 2. 用户余额不足
> 3. 订单已发货不能取消
> 4. 退款金额计算正确

第3轮：运行测试

> /run mvn test -Dtest=OrderServiceTest

> 有个测试失败了，看下是什么问题

第4轮：修复测试

> 原来是 Mock 没设置对，修复下
> /run mvn test -Dtest=OrderServiceTest -v

✅ 结果

• 测试覆盖率：0% → 95%
• 测试用例：28 个
• 发现潜在 Bug：3 个
• 代码质量提升

---

4. 场景4：API 开发

🎯 目标

快速开发一个 RESTful API 接口。

📝 需求

开发一个用户管理 API：
- GET /api/users - 获取用户列表（分页）
- GET /api/users/{id} - 获取单个用户
- POST /api/users - 创建用户
- PUT /api/users/{id} - 更新用户
- DELETE /api/users/{id} - 删除用户

💬 对话过程

第1轮：生成基础代码

codex

> 根据以下需求开发用户管理 API：
> 
> 1. GET /api/users - 获取用户列表（分页）
> 2. GET /api/users/{id} - 获取单个用户
> 3. POST /api/users - 创建用户
> 4. PUT /api/users/{id} - 更新用户
> 5. DELETE /api/users/{id} - 删除用户
> 
> 技术栈：Spring Boot 3.3 + MyBatis-Plus
> 数据库：MySQL
> 遵循项目的编码规范

第2轮：添加验证

> 添加参数验证：
> 1. username：2-50字符，不能重复
> 2. email：必须是有效邮箱
> 3. password：至少8位，包含大小写和数字

第3轮：添加异常处理

> 添加全局异常处理：
> 1. 用户不存在返回 404
> 2. 参数验证失败返回 400
> 3. 重复创建返回 409
> 4. 统一返回 ApiResponse 格式

第4轮：生成文档

> 生成 API 文档，包含请求/响应示例

✅ 结果

• 5 个 API 接口
• 完整的参数验证
• 统一的异常处理
• 自动生成的 API 文档
• 开发时间：15 分钟（传统方式需要 2+ 小时）

---

5. 场景5：数据库迁移

🎯 目标

为一个新功能添加数据库表和迁移脚本。

📝 需求

新增"评论"功能，需要：
1. 创建 comments 表
2. 添加外键关联
3. 创建索引
4. 生成迁移脚本
5. 编写回滚脚本

💬 对话过程

第1轮：设计表结构

codex

> 设计评论功能的数据库表：
> 
> 需求：
> - 支持多级回复
> - 支持点赞
> - 支持软删除
> - 记录创建/更新时间
> 
> 请给出表结构设计，包括字段、类型、索引

第2轮：生成迁移脚本

> 根据设计生成 Flyway 迁移脚本
> 文件名：V2026_05_26_001__create_comments_table.sql

第3轮：生成回滚脚本

> 生成对应的回滚脚本

第4轮：运行迁移

> /run mvn flyway:migrate

> 查看迁移结果
> /run mvn flyway:info

✅ 结果

• 表结构设计合理
• 索引优化到位
• 迁移脚本规范
• 回滚脚本完整
• 耗时：10 分钟

---

6. 场景6：文档生成

🎯 目标

为项目生成完整的 API 文档和 README。

📝 需求

1. 生成项目 README.md
2. 生成 API 接口文档
3. 生成数据库字典
4. 生成部署文档

💬 对话过程

第1轮：生成 README

codex

> 分析项目结构，生成 README.md，包含：
> 1. 项目介绍
> 2. 技术栈
> 3. 快速开始
> 4. 目录结构
> 5. 开发指南
> 6. 部署说明

第2轮：生成 API 文档

> 扫描所有 Controller，生成 Markdown 格式的 API 文档
> 每个接口包含：
> 1. 请求方法和路径
> 2. 请求参数
> 3. 响应格式
> 4. 示例

第3轮：生成数据库字典

> 连接数据库，生成所有表的字段说明文档
> 格式：表名 | 字段名 | 类型 | 说明 | 约束

第4轮：整理输出

> 将所有文档整理到 docs/ 目录
> /export docs/README.md

✅ 结果

• README.md：完整的项目介绍
• API 文档：所有接口详细说明
• 数据库字典：所有表字段说明
• 生成时间：20 分钟

---

7. 场景7：代码审查

🎯 目标

在提交前进行代码审查，发现潜在问题。

📝 场景

# 已经修改了一些文件
git status
# M src/main/java/com/example/service/UserService.java
# M src/main/java/com/example/controller/UserController.java

💬 对话过程

第1轮：查看修改

codex

> /git diff

> 请审查这些修改，找出：
> 1. 潜在的 bug
> 2. 性能问题
> 3. 安全隐患
> 4. 代码风格问题
> 5. 命名是否规范

第2轮：修复问题

> 第3个问题说"缺少空值检查"，请帮我修复

第3轮：再次审查

> /git diff

> 还有其他问题吗？

第4轮：提交代码

> 没问题了，请提交
> /git add .
> /git commit -m "feat: add user validation"

✅ 结果

• 发现 Bug：2 个
• 性能问题：1 个
• 安全隐患：1 个
• 代码风格：3 处
• 审查时间：5 分钟

---

8. 场景8：性能优化

🎯 目标

优化一个慢查询接口。

📝 问题

GET /api/users?department=技术部&page=1&size=20
响应时间：3.2 秒

💬 对话过程

第1轮：分析问题

codex

> 这个接口响应太慢了：GET /api/users?department=技术部
> 响应时间 3.2 秒
> 
> 请分析可能的原因，给出优化方案

Codex 分析：

可能原因：
1. 没有索引（最可能）
2. N+1 查询问题
3. 查询了不必要的字段
4. 没有分页优化

建议：
1. 检查 SQL 执行计划
2. 添加 department 字段索引
3. 使用覆盖索引
4. 优化查询语句

第2轮：执行优化

> 按照建议优化：
> 1. 添加索引
> 2. 优化查询
> 3. 添加缓存

第3轮：验证效果

> /run curl -w "\n%{time_total}\n" http://localhost:8080/api/users?department=技术部

> 响应时间从 3.2 秒降到 0.05 秒，优化效果明显

✅ 结果

• 优化前：3.2 秒
• 优化后：0.05 秒
• 提升：64 倍

---

9. 场景9：Git 操作

🎯 目标

整理 Git 提交历史，准备合并到主分支。

📝 场景

# 当前分支有 10 个提交，需要整理
git log --oneline
# abc1234 fix typo
# def5678 add feature
# ghi9012 wip
# jkl3456 fix bug
# ...

💬 对话过程

第1轮：查看历史

codex

> /git log --oneline -10

> 帮我整理这些提交：
> 1. 合并相关的提交
> 2. 重写提交信息
> 3. 保持功能完整性

第2轮：交互式变基

> 执行交互式变基，将 10 个提交整理为 3 个有意义的提交

第3轮：验证结果

> /git log --oneline -5

> 看起来不错，推送到远程

✅ 结果

• 10 个提交 → 3 个有意义的提交
• 提交信息清晰
• 历史整洁

---

10. 场景10：项目初始化

🎯 目标

从零开始创建一个新的 Spring Boot 项目。

📝 需求

创建一个电商订单服务：
- Spring Boot 3.3
- Java 21
- MySQL
- Redis
- RabbitMQ
- Swagger 文档

💬 对话过程

第1轮：生成项目结构

codex

> 创建一个新的 Spring Boot 项目：
> 
> 项目名：order-service
> 技术栈：Spring Boot 3.3 + Java 21 + MySQL + Redis + RabbitMQ
> 功能：
> 1. 订单 CRUD
> 2. 订单状态管理
> 3. 支付集成
> 4. 消息队列
> 
> 请生成完整的项目结构和基础代码

第2轮：添加配置

> 添加配置文件：
> 1. application.yml（多环境）
> 2. 数据库配置
> 3. Redis 配置
> 4. RabbitMQ 配置
> 5. Swagger 配置

第3轮：生成基础代码

> 生成基础代码：
> 1. 实体类
> 2. Repository
> 3. Service
> 4. Controller
> 5. 配置类

第4轮：验证项目

> /run mvn clean package -DskipTests

> /run mvn spring-boot:run

> 项目启动成功，访问 http://localhost:8080/swagger-ui.html 验证

✅ 结果

• 完整的项目结构
• 可运行的项目
• 包含基础功能
• 创建时间：20 分钟

---

11. 实战技巧总结

💡 高效使用技巧

技巧	说明	示例
明确目标	告诉 Codex 你要做什么	“重构 UserService” 而不是 “看看这个代码”
分步执行	复杂任务拆分为多步	先分析 → 再执行 → 最后验证
提供上下文	给出错误信息、需求文档	“这个 NPE 错误…”
验证结果	每步都运行测试	/run mvn test
使用斜杠命令	比打字更快	/git diff 而不是 “显示 git diff”

🎯 最佳实践

1. 先分析后动手

   # ❌ 直接让 AI 改
   > 重构这个文件
   
   # ✅ 先分析
   > 分析这个文件的代码结构，给出重构建议
   > 好的，按照第2个建议执行
   

2. 保持可回滚

   # 每个重要步骤前创建分支
   /git checkout -b refactor/user-service
   
   # 或者提交当前状态
   /git add . && /git commit -m "checkpoint"
   

3. 验证每一步

   # 修改后
   /run mvn test
   
   # 部署前
   /run mvn clean package
   

4. 利用非交互模式

   # 简单任务直接执行
   codex "为 UserService 生成单元测试"
   
   # 脚本集成
   codex -q "检查代码风格" > report.txt
   

⚠️ 常见陷阱

陷阱	后果	避免方法
一次性给太多任务	AI 混乱	分步执行
不验证结果	引入 Bug	每步测试
不提供上下文	AI 猜测	给出错误信息
盲目信任 AI	可能出错	Review 代码
不保存进度	丢失工作	定期提交

---

12. 总结

🎯 核心要点

1. 代码重构：让 AI 分析 → 给方案 → 执行 → 验证
2. Bug 修复：给错误信息 → 定位根因 → 修复 → 测试
3. 测试编写：指定方法 → 生成测试 → 补充用例 → 运行
4. API 开发：描述需求 → 生成代码 → 添加验证 → 文档
5. 数据库迁移：设计表结构 → 生成脚本 → 运行迁移 → 回滚脚本
6. 文档生成：分析项目 → 生成文档 → 整理输出
7. 代码审查：查看 diff → 找问题 → 修复 → 提交
8. 性能优化：分析瓶颈 → 给方案 → 执行 → 验证
9. Git 操作：查看历史 → 整理提交 → 验证 → 推送
10. 项目初始化：描述需求 → 生成结构 → 添加配置 → 验证

📚 下一步

• 📖 第5篇：避坑指南：新手必看的20个常见问题
• 🔧 实践：选择一个场景，跟着做一遍
• 💬 社区：分享你的实战案例

---

📝 系列文章导航

• 上一篇：第3篇 - AGENTS.md 编写指南：让 AI 理解你的项目
• 下一篇：第5篇 - 避坑指南：新手必看的20个常见问题
• 系列目录：Codex CLI 中文官方手册与使用指南（12篇）

---

💡 遇到问题？ 欢迎在评论区留言，我会及时回复！

👍 觉得有用？ 点赞收藏，帮助更多开发者！