摘要让 Codex 写一个上传组件并不难难的是把上传限制、错误处理、接口调用、进度展示和测试验证全部做完整。本文以后台管理系统的文件上传功能为例分享如何把真实需求拆成可执行任务并让 Codex按照“分析项目、设计方案、修改代码、运行测试、检查 Git Diff”的流程完成交付。很多开发者第一次使用 Codex 做项目时习惯直接输入帮我做一个文件上传功能。这样的任务看起来明确实际上仍然缺少很多关键信息。例如允许上传什么格式文件大小限制是多少是否支持多文件是否需要显示进度上传失败后能否重试上传成功后返回什么是否需要删除已上传文件接口是否已经存在项目有没有可复用组件修改完成后运行什么测试。如果这些问题没有提前说明Codex 可能生成一个“可以运行”的组件但未必适合当前项目。下面以一个 Vue 3 后台管理项目为例演示完整的任务流程。一、先把需求写成验收标准假设产品需求是商品编辑页面支持上传一张商品主图。不要直接开始写代码先把需求转换成可以验证的标准。功能目标 在商品编辑页面增加主图上传功能。 验收标准 1. 只允许上传 JPG、PNG 和 WebP 2. 单个文件不能超过 5MB 3. 一次只能上传一张图片 4. 上传过程中显示进度 5. 上传失败时显示明确原因 6. 上传成功后显示预览图 7. 用户可以删除并重新上传 8. 保存商品时提交图片地址 9. 不修改现有商品保存接口的其他字段 10. 类型检查、测试和构建必须通过。这一步非常重要。因为“完成上传功能”和“满足全部验收标准”是两件不同的事情。二、让 Codex 先分析现有项目真实项目通常已经存在请求封装消息提示组件表单组件图片预览组件文件上传接口公共类型定义。如果不先分析Codex 很可能重复开发。推荐先输入请分析当前项目不要修改代码。 本次目标是在商品编辑页面增加主图上传功能。 请重点检查 1. 商品编辑页面所在文件 2. 商品表单的数据结构 3. 是否已有上传接口 4. 是否已有上传组件 5. 请求拦截器如何处理错误 6. 消息提示组件如何使用 7. 商品保存接口如何提交图片字段 8. 当前测试框架和验证命令 9. 预计需要修改哪些文件。 先输出分析结果和实现建议。假设 Codex 分析后发现相关文件 - src/views/product/Edit.vue - src/api/upload.ts - src/api/product.ts - src/types/product.ts - src/components/ImageUploader.vue - tests/product/Edit.test.ts 现有能力 - 已有单文件上传接口 - 已有公共消息提示方法 - 商品类型中已经存在 coverUrl 字段 - 项目没有可复用的图片上传组件。这说明本次任务不需要新增上传接口只需要完成组件和页面接入。三、先确定修改范围接下来要限制 Codex 的操作范围。本次允许修改 - src/components/ImageUploader.vue - src/views/product/Edit.vue - src/types/product.ts - tests/product/Edit.test.ts - tests/components/ImageUploader.test.ts 禁止修改 - src/api/upload.ts - src/api/product.ts - 路由配置 - 权限模块 - package.json - Lock 文件 要求 - 不新增第三方依赖 - 不全局格式化 - 优先复用现有请求和提示方法 - 如必须修改范围外文件先说明原因。这一步可以避免 AI 顺手调整接口、依赖或其他业务页面。四、把功能拆成几个小步骤不要让 Codex 一次写完所有内容。可以把任务拆成五个阶段。第一阶段定义组件输入和输出例如type ImageUploaderProps { modelValue?: string; maxSizeMb?: number; disabled?: boolean; }; type ImageUploaderEmits { update:modelValue: [value: string]; error: [message: string]; };需要先确定页面怎么传入当前图片上传成功后怎么返回图片地址上传失败后怎么通知页面是否支持禁用状态。组件接口确定后再写内部逻辑。第二阶段实现文件校验校验要发生在上传请求之前。const allowedTypes [ image/jpeg, image/png, image/webp ]; function validateFile(file: File): string | null { if (!allowedTypes.includes(file.type)) { return 仅支持 JPG、PNG 和 WebP 图片; } const maxSize 5 * 1024 * 1024; if (file.size maxSize) { return 图片大小不能超过 5MB; } return null; }重点是不要只检查扩展名。虽然前端校验不能代替服务端安全校验但可以提前拦截明显不符合要求的文件减少无效请求。第三阶段接入上传接口推荐让 Codex复用现有接口而不是重新封装。请使用项目现有的 uploadImage 方法。 上传流程 1. 用户选择文件 2. 执行格式和大小校验 3. 校验通过后开始上传 4. 显示上传进度 5. 上传成功后读取返回的 URL 6. 触发 update:modelValue 7. 上传失败后恢复可操作状态 8. 显示项目统一的错误提示。如果接口返回结构不明确应该先阅读类型和调用示例不要凭经验猜测字段名称。五、不要忽略上传状态文件上传至少有以下几个状态type UploadStatus | idle | validating | uploading | success | error;不同状态对应不同界面idle可以选择图片validating正在检查文件uploading显示进度禁止重复提交success显示预览和删除按钮error显示失败信息允许重新上传。如果不管理状态容易出现连续点击造成重复上传上传失败后按钮仍然禁用删除图片后进度没有重置用户保存表单时图片仍在上传。可以补充一条业务规则如果图片仍处于上传状态禁止提交商品表单并提示用户等待上传完成。六、错误处理要覆盖多个场景上传失败并不只有“网络错误”。至少要考虑1. 文件格式不支持前端直接拦截不发起请求。2. 文件大小超限显示具体限制例如“图片大小不能超过 5MB”。3. 网络中断恢复上传按钮允许重新选择文件。4. 服务端拒绝读取接口返回的业务错误信息。5. 登录状态失效交给项目统一的请求拦截器处理不要在上传组件内重复实现登录逻辑。6. 返回数据异常如果接口成功但没有返回图片地址需要视为上传失败。可以让 Codex检查请检查上传流程是否覆盖 - 不支持的格式 - 文件过大 - 网络错误 - 接口业务错误 - 登录失效 - 返回结果缺少 URL - 用户重复点击 - 上传中删除图片 - 组件卸载时请求仍未完成。七、页面接入时不要破坏原有表单上传组件完成后需要接入商品编辑页面。例如ImageUploader v-modelform.coverUrl :max-size-mb5 :disabledsubmitting /商品保存时仍然使用原来的表单结构await updateProduct({ ...form, coverUrl: form.coverUrl });这里需要重点检查coverUrl是否允许为空编辑旧商品时能否显示原图删除图片后提交什么值上传完成前能否保存保存失败后是否保留图片返回列表再进入时数据是否正确。不要为了增加上传功能重写整个商品表单。八、让 Codex 补齐测试完成代码后至少要覆盖以下测试。文件校验测试1. JPG 可以上传 2. PNG 可以上传 3. WebP 可以上传 4. PDF 被拒绝 5. 超过 5MB 的图片被拒绝 6. 校验失败时不调用上传接口。上传状态测试1. 上传开始后显示加载状态 2. 上传中不能重复选择文件 3. 上传成功后显示预览 4. 上传失败后恢复按钮 5. 删除图片后清空 modelValue 6. 上传中不能提交商品表单。页面集成测试1. 编辑旧商品时显示原主图 2. 上传新图后更新 coverUrl 3. 删除图片后表单字段清空 4. 保存时提交正确的图片地址 5. 商品其他字段保持不变。可以使用请按照项目现有测试风格补充测试。 不要为了让测试通过而降低断言标准也不要跳过失败用例。九、运行完整验证修改完成后不要只检查页面能否打开。至少运行npm run type-check npm run lint npm run test npm run build如果测试失败先让 Codex 分析原因下面是验证失败日志。 请先判断 1. 哪个步骤失败 2. 是否由本次修改引起 3. 是业务代码问题、测试问题还是环境问题 4. 最小修复方案是什么。 先分析不要直接放宽测试或关闭规则。十、最后检查 Git Diff运行git status git diff --stat git diff重点检查是否修改了允许范围以外的文件是否新增了依赖是否改动上传接口是否影响其他商品字段是否有大面积格式化是否补充了测试是否留下调试日志是否正确处理错误状态。还可以让 Codex输出交付报告请根据本次 Git Diff 输出交付总结。 包括 1. 实现了哪些功能 2. 修改了哪些文件 3. 每个文件的修改目的 4. 覆盖了哪些异常场景 5. 新增了哪些测试 6. 验证命令及结果 7. 仍然存在的风险 8. 是否有无关修改。十一、一个完整的任务提示词下面这份模板可以直接用于类似项目。任务 在商品编辑页面增加单图片上传功能。 功能要求 - 支持 JPG、PNG、WebP - 最大 5MB - 一次只能上传一张 - 显示上传进度 - 支持预览、删除和重新上传 - 上传失败后允许重试 - 保存商品时提交图片 URL - 上传中禁止保存商品。 工作流程 1. 读取 AGENTS.md 2. 分析现有商品表单和上传接口 3. 找出可复用代码 4. 输出实现方案和修改文件 5. 等确认范围后再修改 6. 按最小修改原则实现 7. 补充组件和页面测试 8. 运行类型检查、Lint、测试和构建 9. 检查 Git Diff 10. 输出交付报告。 禁止事项 - 不新增第三方依赖 - 不修改上传接口 - 不修改商品接口其他字段 - 不调整路由和权限 - 不全局格式化代码 - 不跳过测试。总结让 Codex 完成真实项目任务关键不是提示词写得多长而是有没有提供清晰的工程流程。一个可靠的文件上传任务至少需要经过明确需求 → 分析项目 → 限定范围 → 拆分步骤 → 处理异常 → 补充测试 → 运行验证 → 检查 Git Diff。如果只说“帮我做一个上传组件”AI 很容易只完成最表面的代码。当任务目标、修改范围、验收标准和验证方式都写清楚后Codex 才能从代码生成工具逐渐变成可以参与真实项目交付的开发助手。对于偶尔修改单个文件的用户轻量使用通常已经足够如果每天都需要处理多文件任务、持续测试和完整仓库分析再根据实际工作量评估更高版本会更合理。CSDN 文章描述如何让 Codex 完成一个真实开发任务本文以商品图片上传功能为例讲解需求拆解、项目分析、范围限制、异常处理、自动化测试、Git Diff 审查和代码交付流程。参考资料Vue.js 官方文档TypeScript 官方文档Vitest 官方文档Git 官方文档OpenAI Codex 使用文档