Chance.js 生成巴西 CPF 纳税人识别号:chance.cpf() 用法与校验位算法全解析

原创2026-10-06 14:19:322,318 阅读
文章标签:测试

Chance.js 生成巴西 CPF 纳税人识别号:chance.cpf() 用法与校验位算法全解析

CPF(Cadastro de Pessoas Físicas)是巴西自然人的纳税人识别号,常用于巴西地区的表单测试、用户资料模拟与本地化数据生成。本文围绕 chancejs 中 person 模块的 cpf 文档,完整讲解 chance.cpf() 的调用方式、formatted 参数行为,并结合 源码实现 与 测试用例 剖析 CPF 的生成流程与两位校验位的计算原理,帮助你直接落地到需要巴西场景数据的项目中。

一、快速上手:一行代码生成合法 CPF

chance.cpf() 是 Chance 中用于生成巴西纳税人识别号(CPF)的快捷方法,无需任何参数即可调用:

// 基础用法
chance.cpf()

调用一次会返回一个格式完整、校验位合法的 14 位字符串,形如:

chance.cpf();
// => '607.116.899-62'

每次调用都会产生不同的随机结果,返回值的固定形态为 XXX.XXX.XXX-XX:前 9 位是随机主体数字,后 2 位是由算法计算出的校验位。

二、formatted 参数:按需保留或移除标点

CPF 的标准展示格式带有分隔符,但许多存储层或接口(如数据库字段、API 请求体)要求纯数字串。cpf 方法通过 formatted 选项控制输出格式:

// 省略标点,仅返回 11 位纯数字
chance.cpf({ formatted: false });
// => '18641718397'

参数行为小结:

参数 类型 默认值 说明
formatted boolean true 为 true 时返回 XXX.XXX.XXX-XX 格式;为 false 时移除所有非数字字符,返回 11 位纯数字

从源码看,该默认值由统一的 initOptions 机制注入(见下文第三节),即不传任何参数时等价于 chance.cpf({ formatted: true })。

三、源码级剖析:CPF 是如何生成的

chance.cpf 的实现位于 chance.js,完整逻辑如下(为便于阅读做了注释标注):

// CPF; ID to identify taxpayers in Brazil
Chance.prototype.cpf = function (options) {
    options = initOptions(options, {
        formatted: true            // 默认输出带格式的字符串
    });

    var n = this.n(this.natural, 9, { max: 9 });   // 生成 9 位随机数字
    var d1 = n[8]*2 + n[7]*3 + n[6]*4 + n[5]*5 + n[4]*6 + n[3]*7 + n[2]*8 + n[1]*9 + n[0]*10;
    d1 = 11 - (d1 % 11);
    if (d1 >= 10) {
        d1 = 0;                                    // 余数小于 2 时校验位取 0
    }
    var d2 = d1*2 + n[8]*3 + n[7]*4 + n[6]*5 + n[5]*6 + n[4]*7 + n[3]*8 + n[2]*9 + n[1]*10 + n[0]*11;
    d2 = 11 - (d2 % 11);
    if (d2 >= 10) {
        d2 = 0;
    }
    var cpf = '' + n[0] + n[1] + n[2] + '.' + n[3] + n[4] + n[5] + '.' + n[6] + n[7] + n[8] + '-' + d1 + d2;
    return options.formatted ? cpf : cpf.replace(/\D/g, '');
};

整个流程可以拆解为三个关键环节:

1. 默认值注入:initOptions

方法开头调用的 initOptions 是 Chance 内部统一的选项合并工具,定义于 chance.js:

function initOptions(options, defaults) {
    options = options || {};
    if (defaults) {
        for (var i in defaults) {
            if (typeof options[i] === 'undefined') {
                options[i] = defaults[i];   // 未显式传入的属性用默认值填充
            }
        }
    }
    return options;
}

它遵循"缺省补默认"策略:只有用户未显式传入 formatted 时才将其置为 true,从而保证 chance.cpf() 与 chance.cpf({ formatted: true }) 行为完全一致。

2. 随机主体:this.n + this.natural

9 位主体数字通过 this.n(this.natural, 9, { max: 9 }) 生成。其中 n 是 Chance 的批量生成方法(chance.js),它接收一个生成函数、生成个数以及透传给该函数的附加参数,返回一个长度为 9 的数组:

Chance.prototype.n = function(fn, n) {
    testRange(typeof fn !== "function", "Chance: The first argument must be a function.");
    if (typeof n === 'undefined') { n = 1; }
    var i = n, arr = [], params = slice.call(arguments, 2);
    i = Math.max(0, i);
    for (null; i--; null) {
        arr.push(fn.apply(this, params));
    }
    return arr;
};

即重复调用 9 次 natural({ max: 9 }),得到 0~9 之间的 9 位随机数字,作为 CPF 的主体部分。

3. 校验位:巴西官方加权求余算法

CPF 的后两位并非随机数,而是由前 9 位数字按巴西官方算法计算而来,这也是生成结果能通过校验的关键:

第一位校验位 d1:前 9 位数字按权重 10、9、8、7、6、5、4、3、2 加权求和,对 11 取余后用 11 减去余数;若结果大于等于 10(即余数小于 2),校验位取 0:

d1 = 11 - ((n0×10 + n1×9 + ... + n8×2) % 11)
d1 >= 10 时 d1 = 0

源码中 n[8]*2+n[7]*3+...+n[0]*10 的书写顺序正是从末位(权重 2)到首位(权重 10)的加权求和。

第二位校验位 d2:将 d1 纳入计算,前 10 位(9 位主体 + d1)按权重 11、10、9、8、7、6、5、4、3、2 加权求和,同样取模 11 求补:

d2 = 11 - ((d1×2 + n0×11 + n1×10 + ... + n8×3) % 11)
d2 >= 10 时 d2 = 0

最终将 9 位主体与两个校验位按 XXX.XXX.XXX-XX 模板拼接;当 formatted 为 false 时,通过 cpf.replace(/\D/g, '') 正则移除全部非数字字符,得到 11 位纯数字串。

四、测试用例验证:输出必为合法形态

仓库的 person 模块测试 对 cpf() 做了严格的批量断言,可作为使用与接入时的参考:

// chance.cpf()
test('cpf() returns a random valid taxpayer number for Brazil citizens (CPF)', t => {
    _.times(1000, () => {
        let cpf = chance.cpf()
        t.true(_.isString(cpf))
        t.true(/^\d{3}.\d{3}.\d{3}-\d{2}$/m.test(cpf))
        t.is(cpf.length, 14)
    })
})

测试在 1000 次迭代中验证了三个约束:

  • 返回值必然是字符串类型;
  • 形态必须匹配 ^\d{3}.\d{3}.\d{3}-\d{2}$(三个 3 位数字块、一个 2 位数字块,以 . 和 - 分隔);
  • 格式化输出的长度固定为 14(含 3 个分隔符)。

五、同族方法与延伸:从 CPF 到 CNPJ

CPF 对应巴西自然人识别号,而在同一源码区域中还提供了面向企业的 CNPJ 生成器(chance.js),两者都遵循"随机主体 + 加权求余校验位"的同一设计模式,只是主体位数(12 位)、权重分配与 d1 阈值判断(d1 < 2 时取 0)不同。当你的项目需要完整的巴西身份场景数据时,可将二者结合使用。

在 person 模块文档 中,cpf 与 aadhar(印度)、ssn(美国)等同属区域化身份标识生成能力,适合在需要多国本地化测试数据的场景中按国家维度选用。

六、典型应用场景与注意事项

适用场景:

  • 巴西站点的注册、表单、下单流程的前端演示数据或自动化测试数据;
  • 需要"格式合法、可通过基础校验"的 CPF 占位数据(数据库种子、接口 Mock);
  • 与 formatted: false 结合,产出符合后端存储规范的 11 位纯数字。

注意事项:

  • 该方法的输出虽满足 CPF 官方校验算法,但它是随机生成的虚拟号码,不代表任何真实存在的巴西公民身份,切勿用于身份认证、风控或任何真实业务决策;
  • 若需求是"校验用户输入的真实 CPF 是否合法",应使用专门的校验库而非本生成器;
  • 当前仓库的 Chance 版本为 1.1.13(见 chance.js),cpf 方法的 formatted 行为以该版本实现为准。

小结:chance.cpf() 是 Chance 提供的一个实现完整、输出可校验的巴西 CPF 生成器——默认输出带分隔符的 14 位字符串,传入 { formatted: false } 即可获得 11 位纯数字。理解其 initOptions 默认值注入、n + natural 批量随机与加权求余校验位算法后,你不仅能正确使用它,还能在需要时按同样思路扩展其他地区识别号的生成逻辑。

登录后查看全文
chancejs