mobile wallpaper 1mobile wallpaper 2mobile wallpaper 3mobile wallpaper 4
3683 words
9 minutes
Spec Coding 实践
2026-04-11
2026-09-27

“帮我做一个 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/import
Content-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. 日常使用,不必每次都写这么长#

这篇用一个完整功能展示了流程。实际工作中,文档的长度应该跟不确定性匹配。

修改按钮文案,写清位置、目标文本和查看方式即可。新增一个有重复判断、部分失败和并发要求的导入功能,就值得提前写出规则和样例。还没确定方向的原型,也可以先探索,再把准备保留的行为整理成规格。

我最常用的检查只有三个问题:

  1. 行为明确吗? 两个开发者读完,会不会做出不同的业务结果?
  2. 范围清楚吗? AI 能否区分本次要做的内容和顺手扩展的内容?
  3. 结果可验证吗? 能否拿一组输入,写出预期输出和检查方式?

能回答这三个问题,Spec 就已经开始发挥作用。它的价值体现在每次实现、审查和修改时,都有一份可以共同对照的依据。

Share

If this article helped you, please share it with others!

Spec Coding 实践
https://mizuki.mysqil.com/posts/spec-coding/
Author
梦幻晨风
Published at
2026-04-11
License
CC BY-NC-SA 4.0

Some information may be outdated

Table of Contents