VALIDATION DESIGN

卡号校验错误设计:校验顺序、提示文案与测试矩阵

把所有失败都显示成“卡号无效”看似简单,却会让用户难以纠正输入,也让 QA 无法定位回归。更好的做法是让内部错误原因精确、外部文案安全且可操作。

先规范化,再按固定顺序校验

输入首先应作为字符串处理,只移除产品明确允许的显示字符,例如空格和连字符。随后检查空值、非法字符、全局长度、候选卡组织长度,最后执行 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 原因码和日志字段。规则表更新时,重叠前缀与长度边界应有专门回归用例。