“帮我做一个 Excel 账单导入功能。”
这句话足够让 AI 开始写代码,却不足以判断它写得对不对。遇到一行错误时,是整批回滚,还是跳过这一行?同一份文件上传两次,应该新增两批账单,还是提示重复?这些选择都能写成能运行的代码,但对应的产品行为完全不同。
我在这篇文章里把 Spec Coding 理解为一种工作方式:先把关键行为写成可检查的规格,再用它指导实现和验收。这不是某个工具独有的功能,也不要求使用一套固定的文档格式。
真正需要改变的是完成标准:从“代码已经生成”变成“约定的行为已经实现,并且有验证结果”。
1. 先分清规格、方案和任务
这三种内容很容易混在一份长提示词里。分开之后,讨论会清楚很多。
| 文档 | 主要回答 |
|---|---|
| Spec:功能规格 | 用户会得到什么行为? |
| Plan:实现方案 | 在当前项目里怎么实现? |
| Tasks:执行任务 | 按什么顺序完成和验证? |
以账单导入为例,“错误行不影响有效行”属于规格;“每行使用独立事务保存”属于方案;“实现单行保存并验证失败隔离”属于任务。
区分它们的意义在于:方案可以调整,用户承诺的行为不能跟着悄悄改变。如果独立事务性能不够,可以寻找别的实现方式,但仍然要满足有效行能够导入的约定。
小改动不必建三个文件。一段包含行为、边界和验证方法的说明就够了。下面把文档拆开,是为了展示一个有多条业务规则的功能如何落地。
2. 从一句需求里找出需要决定的事
假设我们维护一个个人记账应用,用户希望把已有账单批量导入。第一版只接收应用提供的标准模板。
在写实现之前,我会先把影响结果的问题列出来:
- 账单如何识别重复?同一天花了两次相同金额,可能是两笔真实消费。
- 金额代表支出还是收入?允许负数和小数点后三位吗?
- 文件损坏、表头错误、单行错误,是否采用相同的失败方式?
- 重复上传时,相同流水号但内容变了,覆盖旧记录还是报错?
- 导入结果怎样让用户找到有问题的那一行?
这一步不是要求一次性穷举所有异常,而是找出 会改变业务结果的空白。颜色、变量名通常可以沿用项目约定;重复判定和覆盖规则则需要明确。
下面选择一组规则作为本文案例。它们是这个示例的产品决定,不能直接当作所有账单系统的通用规则。
3. 写出一份能用来验收的 Spec
下面的内容可以保存为 docs/specs/bill-import/spec.md。规格中的编号用于后续关联任务和测试。
目标与范围
用户上传标准 XLSX 模板后,可以导入自己的支出账单,并查看每行的处理结果。
第一版只处理人民币支出,只读取第一个工作表,不提供列映射、收入导入、覆盖更新和撤销导入功能。一次请求最多接收 5 MiB 文件、1,000 条非空数据行。
这里明确“第一版不做什么”,是为了让实现范围可控。例如,用户选错列时应该获得模板错误,而不是顺手引入一个列映射配置页面。
输入约定
表头位于第一行,顺序固定为:
流水号 | 日期 | 金额 | 分类 | 备注为了避免 Excel 自动转换带来的歧义,模板将流水号、日期和金额列预设为文本。日期必须填写 yyyy-MM-dd,金额按元填写,例如 18.50;导入器拒绝这三列的非文本单元格。所有列都不接受公式单元格。
完全空白的行忽略,不计入总数;错误结果保留工作表中的原始行号。因此,中间空了一行,也不能让后面的错误行号整体减一。
业务规则
R1:文件级校验。 文件超过限制、无法解析为 XLSX、表头不符,或者非空数据行超过 1,000 条时,整批拒绝,写入数量为零。必须在开始保存账单前完成这些检查。
R2:字段校验。 流水号去除首尾空白后必须非空,长度不超过 64 个字符。日期必须是真实存在的日历日期。金额只接受整数部分和可选的一至两位小数,必须大于零且不超过 999,999.99 元;不接受逗号、科学计数法或超出两位的小数,也不进行自动四舍五入。
金额在业务层转成整数分,例如 18.50 → 1850。这是为了让存储、比较和测试使用同一单位。
R3:字段归一化。 分类和备注去除首尾空白。空分类或不在用户现有分类中的值统一归为“未分类”;空备注保存为空字符串。分类最长 50 个字符,备注最长 500 个字符。重复内容比较使用归一化后的值。
R4:重复与冲突。 本入口的来源固定为 manual-xlsx,使用“当前用户 + 来源 + 流水号”识别同一笔导入记录。流水号由上传者提供;相同编号不用于表示两笔不同账单。
同一个键已经存在时,比较日期、金额分、分类和备注:全部相同则计为重复,不新增记录;任一字段不同则计为冲突,不覆盖旧账单。文件内按原始行号处理,后面的同键记录遵循同一规则。
R5:行级失败。 文件级校验通过后,字段错误或内容冲突只使当前行失败,其余有效行继续处理。账单归属来自当前登录用户,不从工作表读取用户标识。
R6:结果可核对。 返回非空数据行总数、成功数、重复数和失败数,以及每个失败行的行号、错误代码和说明。每条非空数据行只归入一种结果:
total = succeeded + duplicated + failed分类错误会被归一化,金额错误会使当前行失败,表头错误会拒绝整批。这三者不能只用一句“支持异常处理”带过。
接口约定
本文假设项目已有登录机制和统一错误格式,新增接口为:
POST /api/bills/importContent-Type: multipart/form-data请求只有一个名为 file 的文件字段。完成逐行处理后返回 HTTP 200,部分行失败也通过结果字段表达;文件级校验失败返回 HTTP 400,并沿用项目的错误响应格式。未登录和系统故障沿用项目已有约定。
一次正常完成的处理结果示例:
{ "total": 5, "succeeded": 2, "duplicated": 1, "failed": 2, "errors": [ { "row": 3, "code": "INVALID_DATE", "message": "日期不是有效的 yyyy-MM-dd 日期" }, { "row": 6, "code": "BILL_CONFLICT", "message": "流水号已存在,且账单内容不同" } ]}系统中断不伪装成一次完整的导入结果。由于本例允许逐行保存,中断前可能已有账单落库;恢复后重新上传,已成功保存的相同记录按 R4 计为重复。这项约定也需要出现在页面提示中。
4. 用一组具体数据检查规格是否说得通
有了规则,先不要急着写代码。准备一份小文件,在脑中或纸上走一遍,就能发现不少遗漏。
假设当前用户还没有导入过这些流水号,已有“餐饮”分类。模板中的金额和日期都是文本:
行号 流水号 日期 金额 分类 备注2 B001 2026-04-01 18.50 餐饮 早餐3 B003 2026-02-30 12.00 餐饮 午餐4 B001 2026-04-01 18.50 餐饮 早餐5 B002 2026-04-02 30.00 打车6 B001 2026-04-01 20.00 餐饮 早餐结果应该是:
| 行号 | 处理结果 |
|---|---|
| 2 | 成功,金额保存为 1850 分 |
| 3 | 失败,2 月 30 日不存在 |
| 4 | 重复,与第 2 行内容一致 |
| 5 | 成功,分类为“未分类” |
| 6 | 冲突,同一流水号的金额不同 |
因此,前面的响应不是随便写的示意数字,而是这份输入可以推导出的结果:共 5 行,成功 2 行、重复 1 行、失败 2 行。
这时再问一句“原文件上传第二次会怎样”,就得到另一条验收场景:成功数为 0,重复数为 3,失败数仍为 2,数据库不新增账单。
5. 让 AI 根据仓库写方案
规格回答了业务行为,但还没有决定应该修改哪些代码。这个问题需要结合真实项目,而不是凭空生成一套 Controller、Service 和 Repository。
可以把下面这段交给 AI:
请阅读 docs/specs/bill-import/spec.md,以及仓库中账单保存、登录用户获取、文件上传和错误响应的现有实现。
先给出一份简洁的实现方案:1. 列出实际存在的相关文件和准备修改的位置。2. 说明文件级检查、行级校验、重复判断和保存的先后顺序。3. 将 R1—R6 对应到实现位置及验证方法。4. 标出仍缺少的信息;不要把猜测写成已有事实。
优先复用项目现有结构。若发现规则冲突或需要改变公开接口,先指出具体问题;其余已经明确的部分可以继续推进。重点看方案能否守住几个容易写错的地方:文件级校验是否先于写入,部分失败是否被一个大事务全部回滚,重复判断能否在并发上传时仍然成立。
例如,只做一次“查询不存在再插入”并不足以解决并发重复。方案需要落到数据库唯一约束,处理唯一键冲突后,再读取记录判断它是重复还是内容冲突。具体事务写法取决于当前项目的数据库和框架,不应从通用提示词直接猜出来。
6. 把任务拆到可以验证的程度
任务列表的作用是控制改动和建立反馈,不是让每完成一个文件都重新等待批准。
| 任务 | 本步验证重点 |
|---|---|
| T1:解析与文件检查 | 表头、大小、行数、公式拒绝 |
| T2:行校验与归一化 | 日期、金额单位、分类和备注 |
| T3:重复判断与保存 | 重复、冲突、并发、失败隔离 |
| T4:接口与结果展示 | 登录归属、计数、原始行号 |
每个任务完成时记录改了哪里、运行了什么检查、还有什么未验证。已经明确且在范围内的步骤可以连续完成;遇到会改变规格的决定,再把分歧交给需求方。
例如,T2 的测试不应只断言“某个方法返回了对象”,而要断言:
输入金额 "18.50" → 保存值为 1850输入金额 "18.505" → 当前行失败,不进行舍入输入日期 "2026-02-30" → 当前行失败输入空分类 → 归一化为“未分类”这些检查来自业务规则,即使将来更换实现,也仍然有用。
7. 验收时,把承诺和证据放在一起
“测试通过了”还不够,需要知道通过的测试覆盖了什么。
对于这个案例,至少应核对以下行为:
- 标准样例得到
2 成功 / 1 重复 / 2 失败,错误行号为 3 和 6。 - 同一文件重传得到
0 成功 / 3 重复 / 2 失败,没有新增账单。 - 非法表头和 1,001 条非空数据行都不会产生任何写入。
- 两个用户使用同一流水号时,各自导入成功。
- 同一用户并发上传同一笔账单,最终只保存一条记录。
- 模拟中途故障后重传,已保存的记录被识别为重复。
纯字段规则适合单元测试;唯一约束、事务和并发行为需要连接测试数据库验证。只用 Mock 模拟 Repository 返回值,无法证明真实数据库能守住唯一性。
最后再检查 diff:是否改了无关模块,是否引入了规格没有要求的覆盖更新,前端提示与后端实际行为是否一致。AI 的完成总结可以作为索引,不能替代这些证据。
8. 需求变了,先改哪一层
假设后续用户提出:“有些历史账单没有流水号,也想导入。”
这不是把必填校验删掉就能完成的小改动。它直接影响 R4 的重复定义,也影响重传、并发和中断恢复。
我会先更新 Spec,明确没有流水号时采用什么身份规则,以及是否接受误判重复的可能;再调整方案、任务和用例。原来“重复上传不新增”的测试,应该明确保留、修改还是不再适用。
让规格和代码一起出现在同一次变更里,后来维护的人才能知道:这是经过讨论的行为变化,还是一次无意间的回归。
9. 日常使用,不必每次都写这么长
这篇用一个完整功能展示了流程。实际工作中,文档的长度应该跟不确定性匹配。
修改按钮文案,写清位置、目标文本和查看方式即可。新增一个有重复判断、部分失败和并发要求的导入功能,就值得提前写出规则和样例。还没确定方向的原型,也可以先探索,再把准备保留的行为整理成规格。
我最常用的检查只有三个问题:
- 行为明确吗? 两个开发者读完,会不会做出不同的业务结果?
- 范围清楚吗? AI 能否区分本次要做的内容和顺手扩展的内容?
- 结果可验证吗? 能否拿一组输入,写出预期输出和检查方式?
能回答这三个问题,Spec 就已经开始发挥作用。它的价值体现在每次实现、审查和修改时,都有一份可以共同对照的依据。
If this article helped you, please share it with others!
Some information may be outdated






