一张单据上的订单日期、一笔审计记录的事件时间、一份班表上的上班时刻,回答的是不一样的问题。但进了 DataSet,前两个都是 DateTime 列,第三个是字符串列,光看字段类型分不出来,所以「这一列是什么」得由定义层另外交代。
界面要靠它挑编辑控件,数据库要靠它挑原生类型,客户端与服务器之间传递时,也要靠它决定要不要做时区转换(那是明天的题目)。这几件事都无法只从「它是 DateTime」判断。
本篇说明:
- 三种时间语义的判别法
- 日历日与时间点在
DataSet里同为DateTime,语义靠什么保留 - 时刻为什么不用数据库的原生时刻类型
- 未填与越界
一、这个值需不需要知道是哪一天
排班表上的 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 铁人赛参赛文章,原文为繁体中文。
系列完整目录:ERP 架构师笔记:定义驱动的框架设计