Value Objects作为API契约是否可行？实现方案选型咨询

优先选择简单数据契约对象（DTO）作为API入参，在控制器Action内部映射为领域值对象的方案，不推荐直接将核心领域层的Value Objects作为API对外契约使用。

直接用Value Objects做API契约的核心问题 #

• 序列化/反序列化逻辑和值对象的设计原则天然冲突。值对象的核心特性是不可变、构造即完成业务校验、全程保持合法状态，但绝大多数JSON序列化器默认依赖无参构造函数、公开可写属性完成反序列化。实际开发中很多团队踩过这个坑，最后要么妥协给值对象加无参构造、公开可写属性，把值对象改得和普通DTO没区别，白做了领域建模；要么写一堆自定义JSON转换器，每次值对象调整字段都要同步改转换器，维护成本极高，还会直接废掉值对象自带的合法性校验能力。
• 边界耦合严重。API契约是对外暴露的，需要兼容调用方的各类需求，比如旧版本参数兼容、临时字段适配、入参格式调整，这些变动如果直接作用在领域层值对象上，会频繁污染核心领域逻辑，违反架构分层的解耦原则。

推荐方案的优势 #

你提到的第二种实现方式边界划分非常清晰：

• 简单数据契约对象专门对接HTTP请求序列化、接口层参数校验（比如必填校验、长度/格式校验），完全适配序列化器的要求，调整对外参数规则时不会影响核心领域代码。
• Action层完成DTO到值对象的映射时，会自然触发值对象的构造校验逻辑，保证进入业务流程的值对象始终是合法的，完全保留值对象的设计优势。

对应实现不需要强制依赖对象映射工具，直接调用值对象构造方法即可，示例如下：

public IActionResult Post(CreateOrderContract contract)
{
    // 映射为值对象时自动完成地址合法性校验
    var shippingAddress = new Address(contract.Province, contract.City, contract.Street, contract.PostCode);
    // 后续业务逻辑直接使用合法的值对象
    return Ok();
}

唯一的例外场景：如果值对象本身就是专门为接口层设计的，不属于核心领域层模型，且本身已经适配了序列化规则，不会和领域逻辑产生耦合，那么直接作为API契约使用也没有问题。

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