后端【免费下载链接】libphonenumberGoogles common Java, C and JavaScript library for parsing, formatting, and validating international phone numbers.项目地址https://gitcode.com/gh_mirrors/libp/libphonenumber点击查看免费下载libphonenumber 的metadata目录是一套面向CSV 打包格式元数据的辅助 Java 库用于读取、校验与操作 libphonenumber 各客户端库Java/C/JavaScript背后的事实来源数据。本文以 metadata/README.md 为主体结合 metadata.zip 中的真实数据与 metadata/src/main/java 源码完整讲解该库的定位、CSV 表族结构、构建方式、类型/证据模型以及从 CSV 表生成NumberingScheme与正则表达式的底层原理帮助读者理解 libphonenumber 元数据从结构化表格走向客户端可消费格式的必经之路。一、目录定位为读取与操纵 CSV 元数据而生的辅助库README 明确给出了这个目录的角色它包含辅助库auxiliary libraries专门支撑对 libphonenumber 客户端库使用的CSV 打包元数据的读取与操纵。几个关键事实需要先厘清首个发布版本的边界这一版库纯粹关注 CSV 文件的处理尚未包含将 CSV 数据转换为 libphonenumber 所用的 XML 及其他文本文件的类。也就是说当前仓库里你能直接使用的能力是吃进 CSV、校验并操作生成 XML 的完整工具链是文档中描述的未来计划。演进方向README 预期将来操纵 CSV 元数据并生成 XML 文件的全部工具都会发布在这里到那时CSV 文件将成为 libphonenumber 的事实来源source of truth而基于 XML 的元数据及其他映射文件carrier/geocode/timezone 等将自动从 CSV 派生。当前metadata/src/main/java/com/google/i18n/phonenumbers/metadata/model/NumberingScheme.java的类注释印证了这一点——它描述为单一国家区号下所有电话号码元数据的抽象且期望 CSV 表与其他主数据源在业务逻辑的单一点上构建 numbering schemes。支持与 API 稳定性声明README 用加粗强调——这些库当前不受官方支持不提供稳定 API使用风险自负API 虽不会剧烈变化但调整与 bug 修复不可避免。问题与贡献渠道该代码库不接受直接提交的补丁/Pull Request发现问题请开 issue当前阶段不接受功能请求也不提供本目录相关的答疑或技术支持。从源码目录看这套库的组织非常清晰metadata/src/main/java/com/google/i18n/phonenumbers/metadata 下按职责分为五个子包子包职责代表类tableCSV 表格基础设施解析、schema、行列模型、RangeTableCsvParser.java、CsvSchema.java、CsvTable.java、RangeTable.javamodel各类 CSV 表的 schema 定义与领域模型RangesTableSchema.java、MetadataTableSchema.java、NumberingScheme.javaregex从 RangeTree 生成部分优化的正则表达式RegexGenerator.java、NfaFlattener.javafinitestatematcher将号码范围编译为有限状态匹配器DigitSequenceMatcher.java、MatcherCompiler.javai18n区域码与语言标签的值类型PhoneRegion.java、SimpleLanguageTag.java根包下还直接放了一批核心值类型DigitSequence.java、RangeSpecification.java、RangeTree.java、RangeTreeFactorizer.java、PrefixTree.java、LengthsParser.java、MetadataKey.java 等——它们是号码范围建模的最小积木。二、metadata.zip规范元数据的载体与目录结构README 对 metadata.zip 的定义是它包含 libphonenumber 项目的规范元数据canonical metadata供 libphonenumber 工具使用CSV 的 schema 不被承诺保持稳定。用 zip 工具解开该包可以看到本仓库共 1531 个文件其布局与 FileBasedCsvLoader.java 的读取逻辑完全对应metadata/ ├── metadata.csv # 顶层元数据表一行一个国际区号 ├── 1/ # 按国际区号命名的目录如 1、55、65、961… │ ├── ranges.csv # 号码范围表 │ ├── shortcodes.csv # 短号码表 │ ├── examples.csv # 示例号码表 │ ├── formats.csv # 格式表 │ ├── altformats.csv # 备用格式表可选 │ ├── operators.csv # 运营商表可选 │ └── comments.csv # 注释表可选 └── ...FileBasedCsvLoader正是按这套约定实现的构造时读取根目录下的metadata.csvMetadataTableSchema.SCHEMA.load(root.resolve(metadata.csv))loadData(cc)时再进入root.resolve(cc.toString())目录依次加载ranges、shortcodes、examples、formats、altformats、operators、comments七个*.csv文件。值得注意的是没有对应文件的表会被静默视为空表CsvSchema.load 在Files.exists(file)为 false 时直接返回空表。顶层 metadata.csv 的真实样例从metadata.zip中解出的metadata.csv表头与数据行如下分号分隔值可带引号Calling Code ; Main Region ; Extra Regions ; National Prefix ; IDD Prefix ; Timezone ; Mobile Portable Regions ; Extension Prefix 1 ; US ; AG,AI,AS,BB,BM,BS,CA,DM,DO,GD,GU,JM,KN,KY,LC,MP,MS,PR,SX,TC,TT,VC,VG,VI ; 1 ; 011 ; ... ; AG,AI,BB,... 20 ; EG ; ; 0 ; 00 ; Africa/Cairo ; EG 211 ; SS ; ; 0 ; 00 ; Africa/Nairobi这一行的语义由 MetadataTableSchema.java 定义其中Calling Code是行键列其余为非键列列名含义说明Calling Code国际区号行键如1NANPA、20埃及Main Region区号对应的主区域如 NANPA 的主区域是USExtra Regions共享该区号的其他区域逗号分隔如1号段下还覆盖AG,AI,AS,...等加勒比/太平洋区域National Prefix拨打国内号码时的前缀可多个第一个为 preferredUS为1多数国家为0IDD Prefix默认国际直拨前缀可含单个~表示拨号停顿如俄罗斯的8~10该符号仅在生成 XML 的preferredInternationalPrefix时保留Timezone默认时区可多个分隔如Africa/CairoMobile Portable Regions移动号码可在运营商间携号转网的区域列表逗号分隔Extension Prefix分机号首选前缀如extranges.csv 的真实样例美国区号目录1/ranges.csv的头部与几行真实数据Prefix ; Length ; Type ; Tariff ; Area Code Length ; Operator ; Format ; Timezone ; Regions ; Geocode:en ; Provenance ; Comment 201200 ; 10 ; FIXED_LINE_OR_MOBILE ; STANDARD_RATE ; 3 ; ; fmt_3/3/4 ; America/New_York ; US ; Jersey City, NJ 20120[1-9] ; 10 ; FIXED_LINE_OR_MOBILE ; STANDARD_RATE ; 3 ; ; fmt_3/3/4 ; America/New_York ; US ; New Jersey可以看出行键由Prefix可用[1-9]这种范围说明语法与Length支持8,9、5,7-9等长度集合表达两列构成而Geocode:en这类以语言标签命名的列是列组ColumnGroup——详见下文第三节。三、CSV 表族七个表格的 schema 全解CsvDataCsvData.java把单一国际区号下的所有 CSV 表 遗留 XML聚合为一个对象注释明确指出这是能重建全部遗留数据metadata XML、carrier/geocode/timezone 映射的数据来源。它一次加载全部表因为转换到遗留格式往往需要多个数据结构协同。其create()静态工厂会执行三类一致性校验区号必须存在于顶层元数据表中区域一致性ranges 表与 shortcodes 表声明的区域必须与 metadata 表的Main Region/Extra Regions对齐checkRegions行不得重叠ranges 表行之间、shortcodes 表行之间按区域分别计算的号码范围两两不能相交checkNoOverlappingRows。下面逐表介绍 schema全部定义于 metadata/src/main/java/com/google/i18n/phonenumbers/metadata/model。1. Ranges 表号码范围表RangesTableSchema.java 定义行键列PrefixLength以及一组丰富的非键列。其中两个枚举很值得注意ExtType外部号码类型UNKNOWN、FIXED_LINE、MOBILE、FIXED_LINE_OR_MOBILE、VOIP、PAGER、PERSONAL_NUMBER、UAN、VOICEMAIL以及两个未来预留类型M2M机器对机器与ISP拨号上网。注释说明这个外部类型从技术上比 ValidNumberType 更好因为它把类型与资费正确拆开但 phonenumber 库内部逻辑无法直接消化因此最终仍要通过XmlRangesSchema映射回旧的ValidNumberType。ExtTariff外部资费STANDARD_RATE、TOLL_FREE、SHARED_COST、PREMIUM_RATE。将 ExtType 与 ExtTariff 组合后可映射回ValidNumberType如TOLL_FREE资费 →TOLL_FREESTANDARD_RATE不改变类型映射。Ranges 表完整列清单含默认值列类型/取值说明TypeExtType默认UNKNOWN号码范围的语义类型所有行都应赋值TariffExtTariff默认STANDARD_RATE期望资费Area Code Length无符号整数本地拨号时可移除的前缀长度若区号非可选则不填National Only布尔不能从区外拨入派生noInternationalDialling范围Sms布尔是否预期支持 SMSOperator字符串期望运营商carrierID未知可为空Format字符串期望格式 ID无需格式化可为空Timezone时区列表分隔空则隐含默认时区RegionsCSV 列区域列表逗号分隔导入内部表时被规范化为一组布尔列Region:XXGeocode:XXX列组字符串按语言代码组织的 geocode 文本ProvenanceProvenance 枚举该范围为何有效的最重要依据Comment自由文本通常存放与 Provenance 对应的证据链接注意Regions列在 CSV 形态与内部RangeTable形态之间有一个有趣的胖瘦转换RangesTableSchema.toCsv 把一组布尔列Region:XX合并成单个逗号分隔的多值列便于在电子表格中查看toRangeTable 则反向展开成布尔列组便于程序处理。2. Shortcodes 表短号码表ShortcodesTableSchema.java 的行键是RegionPrefixLength三列——注释解释了原因区域必须进入行键因为同一短号码在不同区域可能类型不同NANPA 尤其如此大量区域只有极少量短号码合并到单表最省事。非键列Type必须赋值、Tariff必须赋值、Sms、Carrier Specific是否仅限某运营商源码注释为 Subregion/指定运营商的语义、Provenance、Comment。真实数据1/shortcodes.csv示例Region ; Prefix ; Length ; Type ; Tariff ; Sms ; Carrier Specific AG ; 911 ; 3 ; EMERGENCY ; TOLL_FREE AG ; 988 ; 3 ; EXPANDED_EMERGENCY ; TOLL_FREE BB ; [2359]11 ; 3 ; EMERGENCY ; TOLL_FREE AS ; 40404 ; 5 ; COMMERCIAL ; ; true3. Examples 表示例号码表ExamplesTableSchema.java 行键为RegionTypeValidNumberType非键列Number国内号码与Comment选择该示例的依据。真实数据1/examples.csvRegion ; Type ; Number AG ; FIXED_LINE ; 2684601234 AG ; MOBILE ; 2684641234 AG ; TOLL_FREE ; 8002123456 AI ; FIXED_LINE ; 26446123454. Formats 表格式表FormatsTableSchema.java 行键为Id非键列列约束National必填可含#表示国内前缀占位Carrier可选可含#与运营商说明符后缀必须与 National 兼容International不得含#或Local不得含#或若有 Area Code Length 则必须与之对应National Prefix Optional布尔Comment自由文本真实数据1/formats.csvId ; National ; International ; Local ; National Prefix Optional ; Comment fmt_3/3/4 ; (XXX) XXX-XXXX ; XXX-XXX-XXXX ; XXX-XXXX ; true ; A different pattern is used when formatting internationally... fmt_3/4 ; XXX-XXXX ; XXX-XXXX ; ; true ; 310-xxxx (7 digit) UAN numbers .5. Operators 表运营商表OperatorsTableSchema.java 行键为Id非键列Domestic Selection Codes国内拨号选择码逗号分隔的范围说明、IDD Prefixes国际直拨码、Names:XX按语言的分组名称列。两个使用约定值得注意默认 IDD 前缀不放在本表而是放在顶层 metadata 表的IDD Prefix列若某个选择码/IDD 码不归属任何有号码范围的运营商如通用可用码运营商 ID 必须以__双下划线开头以绕过未赋值运营商的一致性检查。6. AltFormats 与 CommentsAltFormatsSchema.java 定义备用格式表行由备用格式说明符标识含PARENT所对应的主格式 ID等列CommentsSchema负责装载注释。二者在FileBasedCsvLoader中分别经loadAltFormats、loadComments读取且当前CsvData.diff的 TODO 注释表明diff 比较暂未覆盖 comments 与 altformats。四、类型系统与证据体系两个 proto 文件metadata模块把枚举类型放在 proto 文件中构建时由 protoc 生成 Java 类。enums.protoProvenance证据来源enums.proto 定义Provenance枚举注释强调其不稳定且只能存储于基于文本的 protocol buffer 中。取值按可信度递增排列值数值含义UNKNOWN0proto3 的默认值真实数据不应出现ITU10官方 ITU 文档中定义的范围注释应含文档链接最可信IR2120官方 IR21 文档中定义的范围注释应含文档链接GOVERNMENT30官方/政府背书实体网站如国家电信运营商中的证据注释含 URLTELECOMS40电信运营商网站移动运营商、MVNO 等中的证据注释含 URLWEB50非官方网站如 Facebook 或公司主页中的证据注释含 URLINTERNAL100无法引用外部证据的特殊接受情形注释应说明 bug 报告或内部理由只在极特殊情况下使用且注释可能在对外发布时被清除这一枚举直接对应 ranges/shortcodes 表中的Provenance列是每个号码范围为什么有效的审计线索。types.proto号码类型三枚举types.proto 定义了三个枚举XmlNumberTypeXML_UNKNOWN、XML_NO_INTERNATIONAL_DIALLING、XML_FIXED_LINE、XML_MOBILE、XML_PAGER、XML_TOLL_FREE、XML_PREMIUM_RATE、XML_SHARED_COST、XML_PERSONAL_NUMBER、XML_VOIP、XML_UAN、XML_VOICEMAIL。注释要求枚举名必须与 XML 元数据中的元素名忽略大小写一致——这保证了将来 CSV→XML 生成时名称可直接对上。ValidNumberType每个有效号码范围被归类为恰好一种类型不含NO_INTERNATIONAL_DIALLING它是范围的属性而非基本类型。取值与 XmlNumberType 一一对应。XmlShortcodeTypeSC_SHORT_CODE、资费互斥子集SC_TOLL_FREE/SC_STANDARD_RATE/SC_PREMIUM_RATE、以及用途类SC_CARRIER_SPECIFIC/SC_EMERGENCY/SC_EXPANDED_EMERGENCY/SC_SMS_SERVICES。与主元数据不同短号码类型不要求互斥。五、构建方式Maven、protoc 与 AutoValuemetadata/pom.xml 揭示了模块的技术栈Java 11编译目标maven-compiler-plugin3.8.1 配置了两个 executionprocess-annotations在generate-sources阶段以-proc:only运行注解处理器AutoValuedefault-compile在compile阶段以-proc:none编译避免重复处理。protoc-jar-maven-plugin3.11.4内嵌 protoc 3.1.0在generate-sources阶段扫描src/main/proto生成 proto Java 类并加入源码目录。依赖清单均为编译期或测试期依赖依赖版本用途guava32.1.2-jre集合、不可变结构、CharMatcher 等基础设施icu4j73.2Unicode/语言标签处理SimpleLanguageTag等protobuf-java3.24.0proto3 运行时auto-value / auto-value-annotations1.10.2不可变值类型的样板代码生成protoc-jar-maven-plugin3.11.4构建期生成 proto 类jsr3053.0.2Nullable等注解truth / truth-java8-extension1.1.5 / 1.0.1test测试断言测试资源位于 metadata/src/test/java/com/google/i18n/phonenumbers/metadata覆盖CsvParserTest、CsvTableTest、RangeTableTest、RegexGeneratorTest、MatcherCompilerTest、DigitSequenceMatcherTest等另有regression_test_data.textpb用于编译器回归测试。六、核心处理链路从 CSV 到 NumberingScheme 与正则1. CSV ↔ RangeTable 的双向转换Ranges 表在内存中以RangeTable形式工作RangesTableSchema.toRangeTable把 CSV 行还原成带类型化列的范围表toCsv反向导出。这一转换在CsvData.getRangesAsTable()标注Memoized只算一次中被封装canonicalizeRangeTables()则通过转表再转回 CSV来规范化范围表注释提醒大区域可能较慢。2. NumberingScheme单一区号的知识抽象NumberingScheme.java 是单一国家区号已知的所有电话号码元数据的抽象。它的 Javadoc 特别说明不存在 NumberingScheme 的 builder——期望在业务逻辑单一点用 CSV 表等主数据源直接构建测试中可用TestNumberingScheme。而 XmlRangesSchema.java 定义了生成 NumberingScheme 所需的精简列集Type、Area Code Length、National Only、Region:XX布尔列组——它没有配套的CsvKeyMarshaller因为它不是数据导入格式而是内部转换目标。3. RegexGenerator从 RangeTree 到正则正则生成是全链路中最精妙的部分。RegexGenerator.java 从RangeTree产出部分优化的正则表达式核心 APIbasic()不启用任何可选优化结构更简单但输出通常更长defaultXmlGenerator()即BASIC.withDfaFactorization().withSubgroupOptimization()注释明确这是生成与遗留 XML 数据相同正则的默认生成器任何工具想获得与遗留 XML 一致的正则都应使用它另有withDotMatch用.匹配任意数字等开关。生成过程依赖 RangeTreeFactorizer.java 的合并策略ALLOW_EDGE_SPLITTING/REQUIRE_EQUAL_EDGES与 NfaFlattener.java 的 NFA 展平。注意一个工程细节尾部优化tail optimization被有意禁用源码注释说它似乎抵消了子组优化subgroup optimization的收益。4. 有限状态匹配器finitestatematcher子包提供了与正则等价但更高效的匹配方案MatcherCompiler.java 将范围编译为字节码形式的匹配器涉及OpCode.java、Operation.java、Statistics.java运行期由 DigitSequenceMatcher.java 执行CompilerRegressionTest配合regression_test_data.textpb保证编译器输出的稳定性。七、CSV 基础设施解析器与 schema 机制table 子包是整条工具链的地基理解它才能读懂所有 schemaCsvParser.java一个高效、fluent 风格的流式 CSV 解析器。特点包括完整支持引号转义与多行引号值allowMultiline()、可选的空白修剪trimWhitespace()、基于头部行的列映射RowMapper.mapTo且校验表头不能有重复列名、逗号/制表符分隔commaSeparated()/tabSeparated()。源码注释直言这个类之所以必要是因为 Guava 的 CSV 实现不支持忽略空白。CsvSchema.javaschema 键的 marshaller 非键列集合。parseHeader校验前几列是否与键列完全一致parseRow把一行拆成键CsvKeyMarshaller.deserialize与列赋值列表load(Path)对不存在的文件返回空表。CsvTable / RangeTable / CsvKeyMarshallerCsvTable提供导入导出与 diff 能力CsvData.Diff利用CsvTable.diff(..., DiffMode.CHANGES)输出新增/修改/删除的上下文化差异RangeTable用不可变RangeTree组织范围数据并支持OverwriteMode覆盖语义。MetadataExceptionMetadataException.java是贯穿全部校验的异常类型checkMetadata的 Javadoc 强调MetadataException 只应对应可通过修改 CSV 数据修复的问题——这正是CSV 将作为事实来源这一设计意图的直接体现所有错误都应当能在源头数据层被修正。八、结语当前边界与使用建议综合 README 与源码这套元数据处理库的当前边界可以精确概括为能做读取 CSV 元数据FileBasedCsvLoader、按 schema 解析与校验CsvParser/CsvSchema/MetadataException、聚合单一区号数据CsvData、比较快照差异CsvData.diff、构建NumberingScheme、生成正则与有限状态匹配器尚未做把 CSV 转换为 libphonenumber 客户端使用的 XML 元数据及其他映射文件的完整工具README 明示属于未来计划使用注意库不受官方支持、API 不稳定、不接受功能请求——把它当作能读、能验、能操作的实验性工具链而非有兼容性承诺的公共 APIschema 本身也可能演进。对于想深入理解 libphonenumber 元数据结构的读者推荐的阅读路径是先看 metadata/README.md 把握定位再解开 metadata.zip 对照 RangesTableSchema.java 与 MetadataTableSchema.java 理解列语义最后沿着FileBasedCsvLoader → CsvData → NumberingScheme → RegexGenerator这条链路即可完整还原从 CSV 表格到可消费元数据的转换管线。赞分享后端【免费下载链接】libphonenumberGoogles common Java, C and JavaScript library for parsing, formatting, and validating international phone numbers.项目地址https://gitcode.com/gh_mirrors/libp/libphonenumber点击查看免费下载相关推荐libphonenumber 元数据工具链Metadata Tools指南CSV 驱动的号码规划数据模型与 metadata.ziplibphonenumber 元数据工具链Metadata Tools指南CSV 驱动的号码规划数据模型与 metadata.zip 导读 libphon后端移动开发北京昇腾GPT-2安全与偏见分析如何规避AI生成内容风险北京昇腾GPT 2安全与偏见分析如何规避AI生成内容风险 北京昇腾GPT 2作为一款先进的语言生成模型在自然语言处理领域展现了强大的能力。然而与所有大型语从混乱到精准libphonenumber元数据工具链全攻略从混乱到精准libphonenumber元数据工具链全攻略 libphonenumber是Google开发的一套强大的国际电话号码处理库支持Java、C后端移动开发上一篇TradingAgents-CN 配置桥接机制验证与修复实录从 MongoDB 统一配置到环境变量的端到端测试下一篇Langfuse 惰性 JSON 查看器设计剖析字节索引引擎、异步数据源与按需物化的三层架构创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考