首页
/ Vogen：消除原始类型依赖的.NET价值对象生成方案

Vogen：消除原始类型依赖的.NET价值对象生成方案

2026-04-24 09:43:02作者：虞亚竹Luna
Vogen
A semi-opinionated library which is a source generator and a code analyser. It Source generates Value Objects
项目地址：https://gitcode.com/gh_mirrors/vo/Vogen

在现代软件开发中，我们经常使用基本类型（如int、string、decimal）表示业务概念，却忽视了这种做法带来的潜在风险。想象一下，当一个接受用户ID（int）和订单金额（decimal）的方法被错误调用，将金额作为ID传入时，编译器不会发出任何警告——这就是"原始类型依赖"问题，一种常见的代码质量隐患。Vogen通过将基本类型转换为语义化的价值对象，为.NET开发者提供了优雅的解决方案。

Vogen项目标志

理解价值对象的核心价值

价值对象是领域驱动设计中的关键概念，它将基本数据类型与业务规则和约束封装在一起。例如，CustomerId不再是简单的int类型，而是一个包含验证逻辑、业务规则和语义含义的完整对象。这种转变带来三重核心价值：

编译时类型安全：当方法参数从int变为CustomerId时，错误的参数传递会在编译阶段被捕获，而非运行时

业务规则内聚：验证逻辑（如"订单金额不能为负"）被封装在价值对象内部，确保规则在所有使用处一致应用

代码自文档化：CalculateTotal(OrderId id, Money amount)比CalculateTotal(int id, decimal amount)更具可读性，无需额外注释说明参数含义

从零开始集成Vogen

Vogen设计为无缝融入.NET开发流程，通过NuGet包分发，无需复杂的配置步骤。

准备开发环境

在开始前，请确保你的开发环境满足以下条件：

  • .NET 6.0或更高版本SDK
  • 支持C# 9.0或更高版本的开发工具（Visual Studio 2022或JetBrains Rider）

安装Vogen包

打开终端，导航到你的项目目录，执行以下命令安装Vogen：

dotnet add package Vogen

该命令会将Vogen源代码生成器和分析器添加到项目中，无需额外配置即可开始使用。

创建第一个价值对象

创建价值对象只需两个步骤：定义部分类并添加[ValueObject]属性。以下是表示正整数客户ID的示例：

using Vogen;

[ValueObject(typeof(int))]
public partial struct CustomerId {
    // 验证逻辑：确保ID为正数
    private static Validation Validate(int value) {
        return value > 0 ? Validation.Ok : Validation.Invalid("ID必须为正数");
    }
}

编译项目时，Vogen会自动生成完整的价值对象实现，包括相等性检查、转换操作符和验证逻辑。

构建领域模型的实践指南

Vogen提供多种配置选项，帮助你构建符合业务需求的价值对象。以下是几个常见场景的实现方法。

处理字符串类型的价值对象

对于需要特殊格式验证的字符串（如邮箱地址），Vogen提供了灵活的验证机制：

[ValueObject(typeof(string))]
public partial class Email {
    private static Validation Validate(string value) {
        if (string.IsNullOrWhiteSpace(value)) {
            return Validation.Invalid("邮箱不能为空");
        }
        
        if (!value.Contains("@")) {
            return Validation.Invalid("邮箱格式不正确");
        }
        
        return Validation.Ok;
    }
}

实现数值范围约束

对于需要限制范围的数值类型（如年龄），可以在验证方法中添加范围检查：

[ValueObject(typeof(int))]
public partial struct Age {
    private static Validation Validate(int value) {
        if (value < 0 || value > 120) {
            return Validation.Invalid("年龄必须在0-120之间");
        }
        return Validation.Ok;
    }
}

处理自定义基类型

Vogen支持任何可比较的基本类型作为价值对象的基础。以下是使用Guid的示例：

[ValueObject(typeof(Guid))]
public partial struct OrderId {
    // 自定义工厂方法：生成新的订单ID
    public static OrderId New() => From(Guid.NewGuid());
}

实现类型安全的API交互

价值对象在API开发中特别有用，它能确保客户端与服务端之间的数据交换符合业务规则。Vogen自动生成的JSON序列化代码确保价值对象在API调用中正确转换。

Swagger中显示的价值对象参数

ASP.NET Core中的使用示例

在Web API控制器中直接使用价值对象作为参数类型：

[ApiController]
[Route("[controller]")]
public class OrdersController : ControllerBase {
    [HttpGet("{id}")]
    public ActionResult<Order> GetOrder(OrderId id) {
        // id已通过验证，确保是有效的OrderId
        var order = _orderService.GetById(id);
        return Ok(order);
    }
}

客户端请求示例

使用价值对象后，客户端必须提供符合验证规则的数据：

// 正确用法：使用工厂方法创建有效的价值对象
var orderId = OrderId.From(Guid.Parse("550e8400-e29b-41d4-a716-446655440000"));
var response = await httpClient.GetAsync($"/Orders/{orderId}");

// 错误用法：编译时错误，无法直接传递字符串
// var response = await httpClient.GetAsync($"/Orders/550e8400-e29b-41d4-a716-446655440000");

高级配置与扩展

Vogen提供丰富的配置选项，满足复杂业务场景需求。通过属性参数和全局配置，你可以自定义价值对象的行为。

配置序列化行为

控制价值对象在JSON序列化时的表现：

[ValueObject(typeof(string), 
    SerializationMethod = SerializationMethod.Value,
    SystemTextJsonConverter = true)]
public partial class ProductCode {
    // 验证逻辑...
}

实现自定义转换

为价值对象添加与其他类型的转换逻辑：

[ValueObject(typeof(string))]
[Conversion(typeof(int))] // 启用与int类型的转换
public partial class ProductId {
    private static Validation Validate(string value) {
        // 验证逻辑...
    }
    
    // 自定义转换实现
    private static int ConvertToInt(string value) => int.Parse(value);
    private static string ConvertFromInt(int value) => value.ToString();
}

全局配置

通过项目级别的配置文件设置默认行为：

<Project>
  <PropertyGroup>
    <VogenDefaultSerializationMethod>Value</VogenDefaultSerializationMethod>
    <VogenDefaultGenerateValidationException>true</VogenDefaultGenerateValidationException>
  </PropertyGroup>
</Project>

测试价值对象的最佳实践

Vogen生成的价值对象易于测试，因为所有业务规则都封装在对象内部。以下是测试策略建议：

单元测试验证逻辑

[TestClass]
public class AgeTests {
    [TestMethod]
    public void CreateAge_WithNegativeValue_ThrowsValidationException() {
        // Arrange & Act
        Action action = () => Age.From(-1);
        
        // Assert
        Assert.ThrowsException<ValueObjectValidationException>(action)
              .Message.Should().Contain("年龄必须在0-120之间");
    }
}

集成测试与ORM

验证价值对象与Entity Framework Core等ORM工具的兼容性：

[TestMethod]
public async Task SaveCustomer_WithValidId_Succeeds() {
    // Arrange
    var customer = new Customer {
        Id = CustomerId.From(123),
        Name = Name.From("John Doe")
    };
    
    // Act
    _context.Customers.Add(customer);
    await _context.SaveChangesAsync();
    
    // Assert
    var saved = await _context.Customers.FindAsync(customer.Id);
    saved.Should().NotBeNull();
}

解决常见问题与陷阱

尽管Vogen简化了价值对象的创建，但在使用过程中仍需注意一些常见问题：

避免过度使用

不是所有基本类型都需要转换为价值对象。建议对包含业务规则、验证逻辑或具有特殊语义的基本类型使用Vogen。

处理第三方库兼容性

某些库可能不直接支持价值对象类型。此时可使用Vogen生成的Value属性访问底层值：

// 第三方库方法只接受基本类型时
thirdPartyApi.LogValue(customerId.Value); // 使用.Value属性获取底层int值

性能考量

Vogen生成的代码经过优化，性能接近原始类型。对于高性能场景，可通过基准测试验证：

[Benchmark]
public void CreateCustomerId() {
    var id = CustomerId.From(123);
}

探索实际应用案例

Vogen在各种场景中都能发挥价值，以下是几个典型应用案例：

电子商务系统

在订单处理系统中，使用价值对象确保订单ID、产品编码和价格等关键数据的有效性：

public class Order {
    public OrderId Id { get; }
    public CustomerId CustomerId { get; }
    public Money TotalAmount { get; }
    public IReadOnlyList<OrderItem> Items { get; }
    
    // 构造函数确保所有价值对象都经过验证
    public Order(OrderId id, CustomerId customerId, Money totalAmount, IReadOnlyList<OrderItem> items) {
        Id = id;
        CustomerId = customerId;
        TotalAmount = totalAmount;
        Items = items;
    }
}

金融应用

在金融系统中，使用价值对象确保金额、利率等关键数值符合业务规则：

[ValueObject(typeof(decimal))]
public partial struct InterestRate {
    private static Validation Validate(decimal value) {
        if (value < 0 || value > 1) { // 利率在0-1之间
            return Validation.Invalid("利率必须在0到1之间");
        }
        return Validation.Ok;
    }
    
    // 领域行为：应用利率计算
    public Money ApplyTo(Money principal) {
        return Money.From(principal.Value * (1 + Value));
    }
}

医疗系统

在医疗应用中，使用价值对象确保患者ID、诊断代码等符合行业标准：

[ValueObject(typeof(string))]
public partial class DiagnosisCode {
    private static Validation Validate(string value) {
        // 验证ICD-10代码格式
        if (!Regex.IsMatch(value, @"^[A-Z]\d{2}(\.\d{1,2})?$")) {
            return Validation.Invalid("无效的ICD-10诊断代码");
        }
        return Validation.Ok;
    }
}

Vogen通过将业务规则嵌入类型系统，为.NET项目带来了更安全、更可读且更易于维护的代码。无论是小型应用还是大型企业系统，这种价值对象模式都能显著提升代码质量，减少运行时错误，并使业务意图更加清晰。通过本文介绍的方法，你可以立即开始在项目中应用Vogen，体验类型安全带来的诸多好处。

Vogen
A semi-opinionated library which is a source generator and a code analyser. It Source generates Value Objects
项目地址：https://gitcode.com/gh_mirrors/vo/Vogen
登录后查看全文
热门项目推荐
相关项目推荐

热门内容推荐

1 编程实践项目探索指南：从零构建技术能力体系2 技术解构式学习：从0到1构建你的编程知识体系3 构建自己的技术世界：build-your-own-x项目的实践探索指南4 解锁编程技能的实践之旅：从零构建你的技术世界5 技术实践探索：从零开始构建核心系统的实践指南6 亲手锻造技术引擎：从0到1构建核心系统的实践指南

项目优选

收起
docsdocs
暂无描述
Dockerfile
731
4.73 K
pytorchpytorch
Ascend Extension for PyTorch
Python
609
785
kernelkernel
openEuler内核是openEuler操作系统的核心，既是系统性能与稳定性的基石，也是连接处理器、设备与服务的桥梁。
C
433
391
ops-mathops-math
本项目是CANN提供的数学类基础计算算子库，实现网络在NPU上加速计算。
C++
996
1 K
MindSpeed-LLMMindSpeed-LLM
昇腾LLM分布式训练框架
Python
166
197
flutter_flutterflutter_flutter
暂无简介
Dart
983
249
kernelkernel
deepin linux kernel
C
29
16
MindSpeed-MMMindSpeed-MM
华为昇腾面向大规模分布式训练的多模态大模型套件，支撑多模态生成、多模态理解。
Python
145
237
openHiTLSopenHiTLS
旨在打造算法先进、性能卓越、高效敏捷、安全可靠的密码套件，通过轻量级、可剪裁的软件技术架构满足各行业不同场景的多样化要求，让密码技术应用更简单，同时探索后量子等先进算法创新实践，构建密码前沿技术底座！
C
1.1 K
611
atomcodeatomcode
Claude Code 的开源替代方案。连接任意大模型，编辑代码，运行命令，自动验证 — 全自动执行。用 Rust 构建，极致性能。 ｜ An open-source alternative to Claude Code. Connect any LLM, edit code, run commands, and verify changes — autonomously. Built in Rust for speed. Get Started
Rust
1.14 K
146