• 后端

dateparse4cj 是一个基于仓颉（Cangjie）标准库实现的日期时间解析库，CHANGELOG.md 记录了两个版本的演进：v1.0.0 确立了多格式自动识别、时区处理与灵活配置的基础能力，v1.0.1 则新增了微秒级精度、完整月份+星期组合、ANSI Casctime()样式三类格式支持。本文以该变更记录为主线，结合 src/test/date_parse_supply_test.cj、src/constant.cj 等源码与测试用例，逐一印证每个变更点的实际落地位置，帮助你在升级依赖、排查"某格式为何解析不了"时快速定位依据。

v1.0.0：初始版本的核心能力

CHANGELOG 中 v1.0.0 列出了四项 Feature 与一条来源说明，完整原文如下：

• 多格式支持：自动识别并解析几十种常见日期格式，无需指定格式模板。
• 时区处理：内置全面的时区支持，可在不同时区之间准确转换。
• 灵活配置：提供多种解析选项，可定制解析行为。
• 高性能实现：经过优化的解析算法，处理速度快，资源占用少。
• 本项目参考了项目 dateparse（araddon/dateparse），结合仓颉的时间解析特性设计。

这四项特性在当前仓库源码中都有明确对应：

1. 多格式支持：状态机驱动的自动识别

从源码结构看，格式自动识别的核心是一套"逐字符扫描 + 双状态机"实现。src/constant.cj 中定义了DateState枚举（dateStart、dateDigit、dateYearDashDashT、dateWeekdayAbbrevComma等 40 余个状态）和TimeState枚举（timeStart、timePeriod、timeZ等 30 余个状态），分别追踪日期部分和时间部分的解析进度；src/date_parse.cj 中的parseTime方法注释明确列出了支持的格式族：RFC3339、RFC822、ANSIC、UnixDate、RubyDate、RFC850、RFC1123、RFC1123Z、RFC3339Nano、Unix 时间戳，以及20060102、2006-Jan-02、GMT+0800、.999999毫秒等变体。

具体识别逻辑可以参见 src/date_parse.cj 中doParseTime的主循环：首个字符为数字进入dateDigit，为字母进入dateAlpha，否则抛出ExceptionUnknown；遇到-、/、:、.等分隔符时再依据已读长度（例如第 5 个字符遇到分隔符说明前面是 4 位年份）确定具体格式分支。

2. 时区处理：内置时区缩写表与偏移映射

时区支持的数据基础位于 src/constant.cj：timeZones数组内置了约 60 个全球时区缩写（UTC、GMT、CEST、PST、JST、NZST等），timeZoneOffset映射表将每个缩写转换为+8:00、-5:00形式的 UTC 偏移字符串。偏移量的数值转换工具在 src/util.cj 的offsetToSeconds中，同时支持±hh、±hh:mm、±hh:mm:ss三种写法，这正是+0800与+08:00两类输入都能被处理的原因。

对外 API 层面，时区入口集中在 src/date_parse.cj 的三个方法上，默认值行为需注意区分：

完整的 API 清单（含parseFormat、parseDateStr、parseStrAndFormat、parseStrict）及其语义说明可参考 README.md 的"接口说明"一节与 doc/design.md 的DateParse设计章节。

3. 灵活配置：ParserOption 接口与两个内置选项

"灵活配置"对应 src/parser_option.cj 中的ParserOption接口（唯一方法apply(parser: Parser): Unit），以及 src/parser_options.cj 中通过静态工厂方法创建的两个具体选项：

• ParserOptions.preferMonthFirst(Bool)：控制04/02/2014这类"月/日 vs 日/月"不确定的输入，第一个数字优先解释为月份（美式）还是日期（欧式）。实现类PreferMonthFirstOption在apply时调用parser.setPreferMonthFirst(...)。
• ParserOptions.retryAmbiguousDateWithSwap(Bool)：当首次解析因"月份超出 [1,12] 范围"失败时，自动交换月/日并重新解析一次。该重试逻辑的落点在 src/date_parse.cj 的parseTime尾部：捕获到Month value must be in [1, 12]错误后，用取反的preferMonthFirst且关闭重试（避免无限递归）的选项重新走一遍parseTime。

README 中的"配置解析选项功能示例"展示了这两项选项的实际效果：默认解析04/02/2014得2014-04-02，preferMonthFirst(false)下得2014-02-04，而retryAmbiguousDateWithSwap(true)可自动纠正13/02/2014这类月份溢出的输入。

4. 异常模型

v1.0.0 的解析失败路径由两个异常类承担，这也是 CHANGELOG "多格式/时区"能力边界的显式表达：

• src/exception_unknown.cj：ExceptionUnknown，消息为Could not find format for <原字符串>，在状态机无法推进时（如首字符既非数字也非字母）抛出；
• src/exception_ambiguous.cj：ExceptionAmbiguous，消息为This date has ambiguous mm/dd vs dd/mm type format，由parseStrict在检测到月/日歧义标记时抛出（见 src/date_parse.cj）。

v1.0.1：三类新增格式及源码验证

CHANGELOG v1.0.1 原文只有简短的三行，但每一项都能在测试用例与解析状态机中找到对应证据。这三类格式正是"仓库基于测试用例开发"（见 README.md "参与贡献"一节）的直接产物：补充格式先落进测试，再驱动解析器修改。

1. 微秒级精度格式

新增示例：

2024-03-28T15:30:45.123456789 +08:00

对应测试用例位于 src/test/date_parse_supply_test.cj，期望输出为2024-03-28T15:30:45.123456789+08:00，即 9 位小数秒与冒号形式的时区偏移+08:00均被原样保留并正确组合。从源码结构看，该格式落在 ISO/RFC3339Nano 分支上：parseTime的文档注释明确列出RFC3339Nano "2006-01-02T15:04:05.999999999Z07:00"（src/date_parse.cj），而+08:00这类带冒号偏移由 src/util.cj 的offsetToSeconds按h:m形态拆解。主测试集 src/test/date_parse_test.cj 中另有大量.123456精度（微秒 6 位）与+0000 UTC组合的用例，可视为 v1.0.0 已具备、v1.0.1 补齐到纳秒 9 位的连续演进。

2. 完整月份 + 星期组合格式

新增示例：

March 28, 2025 (Friday)

期望解析为2025-03-28T00:00:00Z。测试同样位于 src/test/date_parse_supply_test.cj。从源码结构看，这类输入组合了两个能力：一是dateAlpha状态下对完整月份名的识别（src/date_parse.cj 中将前缀小写后与 src/constant.cj 的months全名表比对）；二是括号内星期说明的处理——时间解析分支中存在对左括号字符的显式处理（src/date_parse.cj 处case r'+' | r'-' | r'('分支），配合 src/constant.cj 中同时收录缩写与全名（fri、friday）的星期表完成匹配。值得注意的是，March既出现在months表、其星期部分friday也同时收录了全名与缩写两种形态，因此(Friday)的大小写变体均可命中。

3. ANSI C asctime() 样式

新增示例：

Fri Mar 28 15:30:45 2025

期望解析为2025-03-28T15:30:45Z，对应测试在 src/test/date_parse_supply_test.cj。这类"星期缩写 + 空格 + 月份缩写 + 日 + 时间 + 年份"的形态在状态机中由dateAlpha（读到Fri这样的 3 字母缩写后）转入dateAlphaWsAlpha分支处理，该分支在 src/date_parse.cj 中给格式模板设置www（星期）与MMM（月缩写）占位。这与 README 中"Go 的标准时间格式"一类用例如Mon Jan 2 15:04:05 2006属于同一格式族，v1.0.1 的用例进一步覆盖了不带时区缩写、年份在时间之后的asctime()典型布局。

三类新增格式的验证方式

补充格式测试集中在独立测试文件 src/test/date_parse_supply_test.cj（类名DateParseSupplyTest），与主测试 src/test/date_parse_test.cj 分离，便于区分"存量格式回归"与"新增格式补充"。用例统一以HashMap<String, String>（输入 → 期望DateTime.toString()结果）组织，并对每个用例使用ParserOptions.retryAmbiguousDateWithSwap(true)选项调用DateParse.default.parseAny（src/test/date_parse_supply_test.cj）。验证流程与 README.md "编译构建"一节一致：

cjpm update cjpm build

版本对照与依赖信息

汇总两个版本的能力边界（均来自 CHANGELOG.md 原文及对应源码证据）：

另需注意版本口径：当前 cjpm.toml 中包名为dateparse，version为1.1.0，cjc-version（构建所需仓颉编译器版本）同样为1.1.0，高于 CHANGELOG 记录到的最新条目 v1.0.1，说明仓库包版本与变更日志条目并非一一对应，阅读时以 CHANGELOG 的实际条目为准。

使用建议与已知边界

结合 CHANGELOG 与 README.md "约束与限制"一节的说明，使用该库时建议：

1. 依赖引用与构建：在cjpm.toml中声明依赖后执行cjpm update、cjpm build（README "使用说明"一节的流程）；测试集可直接运行验证格式支持情况。
2. 歧义日期显式表态：对MM/DDvsDD/MM不确定的输入，默认按美式（月份优先，见 src/parser.cj 中_preferMonthFirst = true的初始值）解释；数据源确定时建议显式传入preferMonthFirst，或在数据管道不可回退时用parseStrict捕获ExceptionAmbiguous做人工兜底。
3. 暂不支持的格式：README 明确列出了ANSIC_GLIBC（Mon 02 Jan 2006 03:04:05 PM UTC）、中文日期（2014年04月18日）、扩展 ISO 8601（2015-02-08 03:02:00 +0200 CEST m=+0.000000001）与 RFC 2822（Tue, 11 Jul 2017 04:08:03 +0200 (CEST)）四类当前不支持的格式，使用前请先用测试方式确认目标格式在支持集合内。
4. 跟进格式演进：本仓库采用"测试用例驱动"的补充模式，新增格式的权威依据是 CHANGELOG 条目与 src/test/ 下的对应用例；若发现未覆盖格式，按 README "参与贡献"一节的说明提交 PR 或 Issue 即可。

• 后端