在C# WebApi中实现基于System.Globalization.Calendar的牙医预约服务

一、关于System.Globalization.Calendar的使用判断 #

System.Globalization.Calendar主要用于处理不同文化体系下的日历规则（比如公历转农历、伊斯兰历适配），如果你的系统仅基于公历实现预约，且不需要多文化日历切换，这个类完全没必要用。你的核心需求是管理牙医可用时段、排查预约冲突、完成预约创建，用DateTime/DateTimeOffset结合业务逻辑就能搞定，用Calendar反而会增加不必要的复杂度。

二、Appointment类的优化方案 #

你现有的Appointment类存在几个可优化的点：

• 拆分Day、StartTime、FinishTime容易出现数据不一致（比如StartTime的日期和Day不匹配），建议合并成StartDateTime和EndDateTime两个字段，Duration直接通过这两个字段计算即可。
• 缺少与牙医的关联，预约必须绑定具体牙医，所以要新增DentistId和Dentist导航属性。
• DataType和DisplayFormat是MVC视图层的特性，WebApi返回JSON时这些特性不会生效，格式化日期时间得靠JSON序列化配置。

优化后的代码：

public class Appointment 
{ 
    public Guid Id { get; set; }

    // 合并日期与时间，避免数据不一致
    public DateTimeOffset StartDateTime { get; set; }
    public DateTimeOffset EndDateTime { get; set; }

    public TimeSpan Duration => EndDateTime - StartDateTime;

    public Guid CustomerId { get; set; }
    public Customer Customer { get; set; }

    // 新增牙医关联字段
    public Guid DentistId { get; set; }
    public Dentist Dentist { get; set; }
}

三、核心业务流程实现要点 #

1. 查询牙医可用时段（建议用GET而非PUT，因为是查询操作） #

• 接口设计：GET /api/dentists/{dentistId}/available-slots?startDate=2024-06-01&endDate=2024-06-30
• 实现逻辑：
  • 先读取该牙医的基础工作规则（比如每周一到周五9:00-18:00，午休12:00-13:00）
  • 查询该牙医已有的所有预约，排除这些占用时段
  • 生成剩余的可用时间段集合返回给前端

2. 创建预约（用POST请求） #

• 接口设计：POST /api/appointments
• 实现逻辑：
  • 接收请求参数：牙医ID、客户ID、预约开始/结束时间
  • 校验：该时段是否在牙医工作时间内、是否与已有预约冲突
  • 校验通过后，写入数据库完成预约

四、日期时间处理注意事项 #

• 优先用DateTimeOffset代替DateTime，避免时区混乱，尤其是服务器部署在不同时区时
• 前端传递日期时间统一用ISO 8601格式（例如2024-06-15T09:00:00+08:00）
• WebApi中配置JSON序列化，确保日期时间格式正确：

builder.Services.AddControllers()
    .AddJsonOptions(options =>
    {
        options.JsonSerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase;
        options.JsonSerializerOptions.Converters.Add(new JsonStringEnumConverter());
        // 配置DateTimeOffset序列化格式
        options.JsonSerializerOptions.Converters.Add(new DateTimeOffsetConverter
        {
            Format = "yyyy-MM-ddTHH:mm:sszzz"
        });
    });

内容的提问来源于stack exchange，提问作者Pikp