Day 27:Date、DateTime 与 Time 的语义分界

一张单据上的订单日期、一笔审计记录的事件时间、一份班表上的上班时刻,回答的是不一样的问题。但进了 DataSet,前两个都是 DateTime 列,第三个是字符串列,光看字段类型分不出来,所以「这一列是什么」得由定义层另外交代。

界面要靠它挑编辑控件,数据库要靠它挑原生类型,客户端与服务器之间传递时,也要靠它决定要不要做时区转换(那是明天的题目)。这几件事都无法只从「它是 DateTime」判断。

本篇说明:

  1. 三种时间语义的判别法
  2. 日历日与时间点在 DataSet 里同为 DateTime,语义靠什么保留
  3. 时刻为什么不用数据库的原生时刻类型
  4. 未填与越界

一、这个值需不需要知道是哪一天

排班表上的 08:00 跟打卡记录上的 08:00 看起来一样,意思不同:前者每天都适用,后者只代表发生过的那一次。

框架的时间字段分成三种语义,判别法是问:这个值需不需要知道是哪一天。

语义 回答的问题 FieldDbType 程序里的类型 时区转换 例子
日历日 哪一天 Date DateOnly 不转换 生日、发票日期、会计期间
时间点 哪一天的几点 DateTime DateTime 转换 创建时间、登录时间戳、打卡记录
时刻 几点(一日之内) Time TimeOnly 不转换 班别起讫、营业时间、提醒时刻

声明方式跟其他字段一样,一个字段一行:

xml 复制代码
<FormField FieldName="hire_date"  Caption="到职日"   DbType="Date" />
<FormField FieldName="created_at" Caption="创建时间" DbType="DateTime" />
<FormField FieldName="work_start" Caption="上班时刻" DbType="Time" />

DbType 同时决定界面默认的控件,对应的就是 Day 7 那张字段对应控件表的第一列:日历日与时间点用日期输入控件,时刻用定宽的时刻输入控件。字段若自己指定了控件,就以指定的为准。


二、在 DataSet 里同为 DateTime 的那两种

日历日与时间点进了 DataSet 都是 DateTime 字段,DateOnly 的值写不进去。框架的处理方式如下:

日历日 Date 时间点 DateTime
DataSet 里的字段类型 DateTime DateTime
字段上的标记 Date DateTime
取值时 用 CDateOnly 取成 DateOnly 用 CDateTime 取成 DateTime

两者类型相同,要靠字段上的标记区分:程序判断时先读标记,没有标记才看 CLR 类型,而 DateTime 一律判成时间点。

标记只管判读,不管写入:程序直接写 row["hire_date"] = DateTime.Now,时分秒会一起留在 DataSet 里,只要日期就自己取 .Date。

各种情况下,标记从哪里来、会不会保留:

情况 标记
依定义创建的字段 创建时就挂上
从数据库读回的表格 框架依 FormSchema 补上
自己写的 SQL 没有定义可查,由写 SQL 的人在查询上列出日历日字段,或事后对表格补标;列名写错会抛异常
经 API 以 JSON 或 MessagePack 送出 另一端会还原

没有标记的日历日列会被当成时间点,而且不会报错,因为它的值本来就是合法的时间点。会在哪里出问题,明天再谈。


三、时刻为什么不用数据库的原生类型

时刻在各处的存放方式:

在哪里 长什么样子
数据库 定长 5 个字符的字符串,例如 "08:30"
DataSet 同一个字符串 "08:30"
程序取值 用 CTimeOnly 转成 TimeOnly
写回 DataSet 单笔表单上的时刻控件会把 "8:30" 补成 "08:30";其他方式写入不一定会补,程序写入要自己用 CTimeString 转

TimeOnly 不能直接放进 DataSet:时刻列是字符串,直接设 TimeOnly 不会抛异常,而是存成当前区域性的文字(zh-TW 下是「上午8:30」);若把字段类型改成 TimeOnly,JSON 与 MessagePack 送表格时又不认得它。所以时刻列的格式定为 "HH:mm" 字符串,取值时再转成 TimeOnly。

程序里用 TimeOnly,因为它表示的就是一天之内的时刻:可以直接比较先后、取出时与分,两个 TimeOnly 相减还能算出时距,例如下班时刻减上班时刻就是工时,跨过午夜的夜班也算得出来。TimeSpan 表示的是一段长度,可以超过一天,也可以是负数,用它存上班时刻,类型挡不住超过一天的值。

数据库不用原生的时间类型,是因为五家不一致:SQL Server 与 PostgreSQL 的 TIME 是一天之内的时刻,MySQL 的 TIME 是一段长度,值域到正负 838 小时,Oracle 则没有 TIME;而前三家的驱动读回来都是 TimeSpan。所以五家一律用字符串:

Date DateTime Time
SQL Server date datetime2(7) nchar(5)
PostgreSQL date timestamp char(5)
MySQL DATE DATETIME(6) CHAR(5)
SQLite DATE DATETIME VARCHAR(5)
Oracle DATE TIMESTAMP(6) VARCHAR2(5)

字符串的好处是直接下 SELECT 就看得懂,而且每笔都补零时,字典序就是时间顺序,WHERE work_start BETWEEN '08:00' AND '17:00' 直接成立;没补零的 "8:30" 会排在 "17:00" 后面,这个条件捞不到它。代价是数据库只会把这一列报成长度 5 的字符串,框架比对结构时得先把定义里的时刻也当成长度 5 的字符串,否则每次升级都会判定有差异。


四、未填与越界

三种语义的取值方法写法一致,方法名就是返回类型,单参数重载一律回 nullable(三个都在 ValueUtilities.Temporal):

csharp 复制代码
DateOnly? day     = ValueUtilities.CDateOnly(row["hire_date"]);
DateTime? instant = ValueUtilities.CDateTime(row["created_at"]);
TimeOnly? start   = ValueUtilities.CTimeOnly(row["work_start"]);

回 nullable 是因为时刻找不到能代表「未填」的值:default(TimeOnly) 是 00:00,而 00:00 本身就可能是上班时刻,用它代表未填,没填的字段会被当成 00:00,也不会报错。日期虽然可以拿 0001-01-01 代表未填,但这个值很容易被印到报表上、被当成数据,所以日期的两个也一样回 nullable。需要非空的值时,用双参数重载自己指定替代值。保存时也一样,时刻没填存的是空字符串,不是 "00:00"。

取值时也会检查格式与范围:CTimeOnly("8:30") 可以接受并当成 08:30,"25:00" 与 30 小时的 TimeSpan 都回空值。字符串字段与 TimeSpan 都装得下超过一天的值,所以范围由取值方法来挡。


回到 Northwind

案例的 FormSchema 里,应用自己的时间字段只有两个,而且是同一种:订单的 order_date 与员工的 hire_date,两份定义上都写着 DbType="Date"。

案例的 TableSchema 里有一批时间点字段,一个都不在应用自己的表上:session 的写入与失效时间、API 密钥的到期时间、定义与缓存通知的更新时间、审计那几张表各自的事件时间,以及框架其他几张表的写入时间。全部是框架自己记录的数据。

原因是两种数据的用途不同。订单日期拿来结账、分期间、比对月结,几点下的单在业务上用不到;session 什么时候失效、哪一秒登录失败,少了时分秒就没有意义。用第一节的判别法来看,应用的表要的是日历日,框架的表要的是时间点。


小结

日历日与时间点在 DataSet 里同为 DateTime,靠字段上的标记区分,没有标记的字段会被当成时间点,而且不会报错。框架创建与读回的表格都会标上,自写的 SQL 则要自己声明日历日字段。

时刻在数据库与 DataSet 里都是定长的字符串,不会被误认成时间点,程序取值时再转成 TimeOnly。代价是数据库只认得它是长度 5 的字符串,框架比对结构时要另外处理。

明天谈这三种类型里唯一会被动到的那一种,也就是时间点的时区转换。日历日与时刻不做转换,转了只会出错,例如生日退到前一天、八点上班变成下午四点。前提是先分得出一列是哪一种。


本文为 2026 iThome 铁人赛参赛文章,原文为繁体中文。

iThome 原文 | HackMD 版

系列完整目录:ERP 架构师笔记:定义驱动的框架设计

相关推荐
sleveen12 小时前
新增办理动词只写 Core:SailFlow 动作骨架、同事务信封与 Sync 钩子自锁治理
开源·.net·工作流·oa引擎
哲霖软件1 天前
非标制造企业四种领料方式怎么选?
erp·哲霖软件·非标自动化
Jeff-Tsai2 天前
Day 26:数值语义、多币种与计量单位
.net·架构设计·erp·definition-driven
风云2 天前
两条 Pipe、五个命门:Vane.NET 内核为什么长这样
开源·网络编程·.net·架构设计·vane.net
宝桥南山2 天前
Visual Studio 2026新特性 - 可以直接连接DeepSeek(使用Custom Endpoint Provider配置项)
ide·microsoft·微软·aigc·.net·visual studio
Jeff-Tsai2 天前
Day 25:审计轨迹与变更的前后值
.net·架构设计·erp·definition-driven
IT规划师3 天前
Redis 核心机制 | 事务:执行序列的原子性、乐观锁与 8.x 条件写
redis·.net
Jeff-Tsai3 天前
Day 24:权限的三轴:动作、行与列
.net·架构设计·erp·definition-driven
BruceNeter4 天前
C# winform卡死问题分析1——线程池子线程创建句柄
c#·.net