先规范化,再按固定顺序校验
输入首先应作为字符串处理,只移除产品明确允许的显示字符,例如空格和连字符。随后检查空值、非法字符、全局长度、候选卡组织长度,最后执行 Luhn。固定顺序能让同一输入始终返回同一主错误。
不要在规范化阶段静默删除任意字符,否则拼写错误可能被改造成另一个有效字符串。前导零和长数字也要求字符串处理,避免数值类型造成精度或格式丢失。
- type:输入不是字符串;API 会在批量映射前返回 NUMBER_TYPE
- empty:字符串中没有可用数字
- characters:出现空格和连字符以外的不支持字符
- global_length:数字长度不在 12–19 位
- network_length:长度不符合候选卡组织规则
- luhn:全局长度合理但校验和失败;reasons 为空表示本地格式检查通过
内部原因码与界面文案应当分离
API 返回稳定的机器原因码,界面再根据语言、字段状态和产品语气生成文案。这样自动化可以断言代码,内容团队可以改进提示,而不会破坏集成。
界面提示应告诉用户下一步,例如“检查数字位数”或“仅输入数字”。但本地通过不能显示成“卡号已验证”,因为 Luhn 与长度都不能证明账户存在或交易可授权。
客户端负责体验,服务端负责信任边界
客户端即时反馈可以减少无效提交,但任何 JavaScript 校验都可能被绕过。服务端必须重新验证类型、长度、允许字符和业务条件,并对请求体和批量数量设置上限。
前后端应共享规则版本或契约测试。若无法共享实现,至少共享原因码定义和一组固定样本,避免前端显示通过而 API 拒绝同一输入。
- 字符串类型而不是 JSON 数字
- 限制请求体与数组大小
- 拒绝未知字段或记录兼容策略
- 响应使用 no-store
- 日志只保存原因码、请求 ID 与必要上下文
用单一变量构建回归矩阵
每个负向样本尽量只破坏一个条件:合法长度但错误校验位、Luhn 通过但卡组织长度不符、包含一个非法字符、空白输入和超长批量。单一变量让失败更容易解释。
同时测试格式化前后值、遮罩结果、可访问错误关联、API 原因码和日志字段。规则表更新时,重叠前缀与长度边界应有专门回归用例。