时间与多时区
本页是时间存储、接口传输、用户展示和多时区上下文的主题页。正式规则请优先阅读 框架规范 / 时间与时区规范。
适用场景
- WebAPI 入参与出参中的时间字段。
- 审计字段、版本字段、日志时间。
- 用户时区展示与多区域业务。
- 后台任务、Job、异步事件中的时间处理。
必须遵守
- 数据库存储时间优先使用 UTC 语义，审计字段默认采用
DateTimeOffset.UtcNow。 - 对外 API 必须明确时间字段语义，不让调用方猜。
- 前后端交互统一使用毫秒 Unix timestamp。
- 不混用本地时间字符串、ISO 时间字符串和 UTC 时间戳。
- 不把服务器本地时区当作用户时区。
- 用户本地显示时间必须基于
WorkContext.TimeZoneInfo或明确用户时区设置。 - 新增时间字段时命名要表达语义，不使用模糊字段名。
推荐做法
- 审计字段使用 UTC 语义时间。
Ts这类字段单独承担并发/版本控制，不当作展示时间。- API 统一使用毫秒时间戳，并在文档里明确字段语义。
- 项目复杂到需要用户时区解析器时，在框架规则之上扩展项目级 resolver。
- 维护旧代码时不随意改变已有字段语义，但要在文档和接口说明里补清楚。
常见坑
- 把
DateTime.Now直接写进跨时区共享数据。 - 一个模块里同时混用多种时间语义而不注明。
- 把前端显示时间和数据库存储时间混为一谈。
- 前端直接显示服务端 UTC 值，不转浏览器本地时间。
- 把审计时间、展示时间和并发版本字段混为一谈。
真实用例
- gmandarin-backend：项目级时间 resolver 体系。
- woscm：
DateTimeOffset.UtcNow审计字段 +ts并发版本双轨设计。