04-Codex CLI 实战

Luhong 收录于 AI工具 Codex CLI

2026-06-09 约 2540 字预计阅读 6 分钟

Codex 实战：项目应用案例

本文是 Codex CLI 系列博客的第 4 篇，将通过多个真实项目场景，展示如何在日常开发中高效使用 Codex。从代码重构到自动化测试，从文档编写到问题排查，覆盖你最可能遇到的开发任务。

1 场景一：快速代码重构

1.1 重构需求描述

假设你有一个遗留的 JavaScript 项目，其中大量使用了回调函数风格的网络请求代码。你希望将其重构为现代的 async/await 风格，以提高代码可读性和可维护性。这是一个非常适合 Codex 处理的场景。

1.2 重构任务执行

首先启动 Codex 并指定项目目录：

codex -C D:\projects\legacy-app "将 src/api/ 目录下所有文件从回调风格重构为 async/await 风格"

Codex 会分析目录结构，识别所有使用回调的网络请求函数，然后逐一进行重构。整个过程你可以通过审批策略控制，确保每处修改都符合预期。

1.3 重构结果示例

重构前：

function fetchUserData(userId, callback) {
    fetch("/api/users/" + userId)
        .then(response => response.json())
        .then(data => {
            callback(null, data);
        })
        .catch(error => {
            callback(error, null);
        });
}

重构后：

async function fetchUserData(userId) {
    try {
        const response = await fetch("/api/users/" + userId);
        const data = await response.json();
        return data;
    } catch (error) {
        throw new Error("Failed to fetch user data: " + error.message);
    }
}

Codex 不仅转换了语法风格，还改进了错误处理方式，使用 throw 而非回调传递错误，这是一个更符合现代 JavaScript 惯用法的方式。

1.4 批量重命名技巧

如果你需要批量重命名变量或函数，可以结合通配符使用 Codex：

codex "将所有文件中 getUserInfo 函数重命名为 getUser，并更新所有引用"

Codex 会找到所有相关文件，完成重命名并确保没有遗漏任何引用。

2 场景二：自动化测试生成

2.1 为现有代码生成测试

当你需要为遗留代码添加测试覆盖时，Codex 可以根据代码逻辑自动生成测试用例。假设你有一个工具函数文件需要测试：

codex "为 src/utils/format.ts 中的所有函数生成 Jest 测试用例"

Codex 会分析每个函数的输入输出逻辑，生成相应的测试用例：

// format.ts 的测试可能如下所示
import { formatDate, formatCurrency, formatPhone } from "./format";

describe("formatDate", () => {
    it("should format date with default locale", () => {
        const date = new Date("2024-01-15");
        expect(formatDate(date)).toBe("2024-01-15");
    });

    it("should format date with custom locale", () => {
        const date = new Date("2024-01-15");
        expect(formatDate(date, "zh-CN")).toBe("2024年1月15日");
    });

    it("should handle invalid date", () => {
        expect(formatDate(null)).toBe("");
        expect(formatDate(undefined)).toBe("");
    });
});

describe("formatCurrency", () => {
    it("should format USD by default", () => {
        expect(formatCurrency(1234.56)).toBe("$1,234.56");
    });

    it("should format with different currencies", () => {
        expect(formatCurrency(1234.56, "CNY")).toBe("¥1,234.56");
        expect(formatCurrency(1234.56, "EUR")).toBe("€1,234.56");
    });
});

2.2 边界条件测试

Codex 生成的测试通常包含基本的正常流程，但你可以通过更具体的提示要求它覆盖边界条件：

codex "为 formatCurrency 函数生成测试，特别关注边界条件：负数、零、超大数值、非数字输入"

这会生成更全面的测试用例，包括异常输入的处理验证。

2.3 集成测试场景

对于 API 接口，Codex 也可以生成集成测试：

codex "为 users API 端点生成集成测试，包括：获取用户列表、创建用户、更新用户、删除用户、异常情况处理"

生成的测试可能使用 supertest 或类似的 HTTP 测试库：

const request = require("supertest");
const app = require("../src/app");

describe("Users API", () => {
    describe("GET /api/users", () => {
        it("should return users list", async () => {
            const response = await request(app)
                .get("/api/users")
                .expect(200);
            
            expect(Array.isArray(response.body)).toBe(true);
        });

        it("should support pagination", async () => {
            const response = await request(app)
                .get("/api/users?page=1&limit=10")
                .expect(200);
            
            expect(response.body).toHaveProperty("data");
            expect(response.body).toHaveProperty("total");
            expect(response.body).toHaveProperty("page");
        });
    });

    describe("POST /api/users", () => {
        it("should create new user", async () => {
            const newUser = {
                name: "Test User",
                email: "test@example.com"
            };
            
            const response = await request(app)
                .post("/api/users")
                .send(newUser)
                .expect(201);
            
            expect(response.body).toMatchObject(newUser);
            expect(response.body).toHaveProperty("id");
        });

        it("should reject invalid email", async () => {
            const invalidUser = {
                name: "Test User",
                email: "invalid-email"
            };
            
            await request(app)
                .post("/api/users")
                .send(invalidUser)
                .expect(400);
        });
    });
});

3 场景三：文档自动生成

3.1 API 文档生成

Codex 可以分析代码并生成格式良好的文档。对于 Express 路由定义：

codex "为 src/routes/ 目录下的所有 API 路由生成 Markdown 格式的 API 文档"

Codex 会解析路由定义、请求参数、响应格式，生成结构化的文档。

3.2 README 文件生成

对于新项目或需要补充文档的项目：

codex "为这个 Node.js 项目生成完整的 README 文档，包括：项目介绍、安装步骤、使用示例、API 列表、贡献指南"

Codex 会分析项目结构、package.json、入口文件等，生成符合项目实际情况的文档。

3.3 代码注释生成

对于复杂的业务逻辑，Codex 可以生成详细的代码注释：

codex "为 src/services/payment.ts 中的所有方法和类添加 JSDoc 注释"

生成的注释会包含参数说明、返回值类型、使用示例。

4 场景四：问题排查与调试

4.1 分析错误日志

当你遇到难以理解的错误时，可以将错误信息提供给 Codex：

codex "分析以下错误信息，说明问题原因并提供解决方案：Error: Cannot read property 'map' of undefined at UserList.js:45"

Codex 会分析错误上下文，给出可能的原因和解决方案。如果结合完整的错误堆栈和部分代码，效果会更好。

4.2 性能问题诊断

对于性能问题，Codex 可以帮助分析代码并找出潜在的性能瓶颈：

codex "分析 src/components/UserTable.tsx 的性能问题，特别是大数据量渲染和重复渲染方面"

Codex 会检查代码并给出优化建议，可能包括：使用 React.memo、使用虚拟列表、避免内联函数等。

4.3 安全漏洞扫描

Codex 还可以帮助识别常见的安全问题：

codex "扫描 src/ 目录下的所有文件，查找潜在的安全问题：SQL 注入、XSS、硬编码密码、不安全的随机数等"

这对于代码审计和安全加固非常有帮助。但请注意，Codex 的安全扫描不能替代专业的安全工具和人工审计。

4.4 调试辅助

在调试过程中，Codex 可以帮助你理解复杂的代码逻辑：

codex "解释 src/utils/complex-parser.ts 中 parseExpression 函数的执行流程，特别是递归处理的部分"

Codex 会详细解释代码逻辑，帮助你快速理解不熟悉的代码区域。

5 效率提升技巧

5.1 使用交互模式保持上下文

对于复杂的多步骤任务，使用交互模式保持会话：

codex
# 在同一个会话中执行多个相关任务
> 为这个 React 组件添加 TypeScript 类型
> 现在添加 Storybook 故事文件
> 接下来生成对应的测试文件

这种方式让 Codex 能够理解上下文，避免重复了解项目结构。

5.2 结合规划模式处理复杂任务

对于需要多步骤完成的大任务，使用规划模式：

codex /plan "为这个项目搭建完整的测试框架，包括：Jest 配置、React Testing Library、测试工具函数、示例测试"

规划模式会先生成详细的执行计划，征得你同意后再逐步执行。

5.3 善用提示词技巧

清晰的提示词能显著提升 Codex 的输出质量：

# 不够具体
codex "优化这个函数"

# 更加具体
codex "优化 getUserList 函数的性能，使用缓存减少数据库查询，并添加分页支持"

具体说明要求、约束条件和期望结果，获得的输出会更加符合需求。

6 小结

本章通过六个真实项目场景展示了 Codex 的实际应用价值。代码重构可以批量处理遗留代码，保持风格一致；测试生成能快速建立测试覆盖，减少手工工作量；文档生成让代码文档保持同步更新；问题排查帮助快速定位和解决问题；日常开发辅助提升编码效率；跨语言转换降低技术栈迁移门槛。

掌握这些场景的应用后，你将能够充分发挥 Codex 的能力，显著提升开发效率。

本文更新于 2026 年 6 月。