Sarmkadan/dotnet-source-generator-toolkit
GitHub: Sarmkadan/dotnet-source-generator-toolkit
一个基于 Roslyn 的 .NET 工具包,通过属性标注自动为实体类生成仓储、映射器、验证器和序列化器等样板代码,以解决企业级应用开发中重复编码的问题。
Stars: 0 | Forks: 1
# .NET 源代码生成器工具包



**一个基于 Roslyn 的代码生成工具包,用于根据属性生成仓储、映射器、验证器和序列化器。**
## 目录
- [概述](#overview)
- [主要特性](#key-features)
- [架构](#architecture)
- [安装](#installation)
- [快速开始](#quick-start)
- [使用示例](#usage-examples)
- [API 参考](#api-reference)
- [配置](#configuration)
- [CLI 参考](#cli-reference)
- [故障排除](#troubleshooting)
- [性能](#performance)
- [测试](#testing)
- [相关项目](#related-projects)
- [贡献](#contributing)
- [许可证](#license)
## 概述
.NET 源代码生成器工具包是一个全面的解决方案,用于在 .NET 10.0 项目中自动化样板代码生成。它基于 Microsoft Roslyn 构建,能够智能分析您的 C# 代码库,并为常见模式生成生产就绪的代码,包括仓储、映射器、验证器和序列化器。
### 动机
企业级 .NET 应用通常需要大量重复性代码:
- 用于数据访问模式的**仓储实现**
- 用于跨层通信的**映射器/DTO 转换**
- 用于强制执行业务规则的**验证逻辑**
- 用于多种格式(JSON、XML、CSV)的**序列化代码**
此工具包通过使用 Roslyn 分析您的实体定义并自动生成完整的、类型安全的实现来消除这种繁琐工作。只需定义一次领域模型,用属性标记它,让工具包处理其余工作。
### 为什么不用代码模板?
传统的代码生成工具依赖于模板,这些模板具有以下缺点:
- **脆弱** - 容易被空格或语法错误破坏
- **难以维护** - 更改需要更新整个代码库中的模板
- **静态分析能力差** - 对您实际类型的上下文了解有限
此工具包使用 Roslyn 的完整语义分析器来理解您的代码结构,确保生成的代码始终是类型安全的,命名空间正确,并在您的模型更改时自动更新。
## 主要特性
### 核心生成能力
**仓储模式生成**
- 根据实体属性自动生成仓储实现
- 支持常见的查询模式(`FindBy*`、`GetAll`、`GetPaged`)
- 内置过滤、排序和分页
- 全程支持 Async/await
**映射器/DTO 生成**
- 实体和 DTO 之间的双向映射
- 嵌套对象映射
- 集合映射并保持元素顺序
- 自定义属性映射规则
- 基于配置的生成(为不同场景生成独立的映射器)
**验证器生成**
- 流畅的验证规则创建
- 内置规则库(`NotEmpty`、`Length`、`Pattern` 等)
- 本地化的错误消息
- 支持异步验证
- 支持带消息的自定义验证规则
**序列化器生成**
- 具有自定义命名策略的 JSON 序列化
- 具有架构验证的 XML 序列化
- 具有表头映射的 CSV 序列化
- 用于性能关键路径的二进制序列化
- 特定于格式的选项和自定义
### 基础设施特性
- **中间件管道**:用于可扩展性的责任链模式
- **事件系统**:用于跨组件通信的解耦发布-订阅消息传递
- **输出格式化**:多种输出格式(JSON、CSV、XML、Text),具有可扩展工厂
- **缓存层**:具有可配置过期策略的内存缓存
- **指标收集**:性能监控和报告
- **批量处理**:具有并行度控制的并行执行
- **HTTP 集成**:内置 webhook 支持,具有重试策略
- **配置管理**:基于文件的配置,带验证
- **日志记录**:贯穿整个管道的结构化日志
### 开发者体验
## 架构
### 高层架构图
```
┌─────────────────────────────────────────────────────────────┐
│ CLI Layer │
│ (CliArgumentParser, CliOptions) │
└──────────────────────┬──────────────────────────────────────┘
│
┌──────────────────────▼──────────────────────────────────────┐
│ Middleware Pipeline │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Logging │→ │ Error Handler│→ │ Validation │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└──────────────────────┬──────────────────────────────────────┘
│
┌──────────────────────▼──────────────────────────────────────┐
│ Generation Pipeline │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 1. Analyze Project (AttributeAnalyzer) │ │
│ │ 2. Extract Entities (EntityAnalyzer) │ │
│ │ 3. Generate Code: │ │
│ │ - RepositoryGeneratorService │ │
│ │ - MapperGeneratorService │ │
│ │ - ValidatorGeneratorService │ │
│ │ - SerializerGeneratorService │ │
│ │ 4. Format Output (FormatterFactory) │ │
│ └─────────────────────────────────────────────────────┘ │
└──────────────────────┬──────────────────────────────────────┘
│
┌──────────────────────▼──────────────────────────────────────┐
│ Output Formatters & Integration │
│ ┌──────────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────────┐ │
│ │ JSON │ │ CSV │ │ XML │ │ Text │ │ Webhooks │ │
│ └──────────┘ └──────┘ └──────┘ └──────┘ └──────────┘ │
└─────────────────────────────────────────────────────────────┘
Supporting Infrastructure:
├── Event System (EventAggregator, GenerationStartedEvent, etc.)
├── Caching (MemoryCache, CacheKey)
├── Metrics (MetricsCollector)
├── Configuration (ConfigurationManager, ToolkitOptions)
└── File I/O (FileSystemService)
```
### 使用的设计模式
| 模式 | 组件 | 用途 |
| :--- | :--- | :--- |
| **中间件** | `Pipeline`, `LoggingMiddleware`, `ValidationMiddleware`, `ErrorHandlingMiddleware` | 可扩展的请求/响应链 |
| **工厂** | `FormatterFactory`, `MiddlewarePipeline` | 创建格式化器和中间件 |
| **仓储** | `EntityRepository`, `GenerationResultRepository` | 数据访问抽象 |
| **观察者** | `EventAggregator`, `IEventPublisher`, `IEventSubscriber` | 解耦的事件处理 |
| **策略** | `IOutputFormatter` 实现 | 多种输出格式策略 |
| **Async/Await** | 所有服务方法 | 非阻塞操作 |
### 组件职责
**分析器** (`Infrastructure/`)
- `AttributeAnalyzer`:在源代码中查找和解析生成属性
- `EntityAnalyzer`:提取实体属性和元数据
**生成器** (`Services/`)
- `RepositoryGeneratorService`:创建 CRUD 实现
- `MapperGeneratorService`:生成双向映射器
- `ValidatorGeneratorService`:创建验证规则
- `SerializerGeneratorService`:构建序列化代码
**基础设施** (`Infrastructure/`)
**格式化器** (`Formatters/`)
- `JsonOutputFormatter`:带元数据的 JSON 输出
- `CsvOutputFormatter`:电子表格兼容格式
- `XmlOutputFormatter`:面向文档的 XML
- `TextOutputFormatter`:人类可读的摘要
- `FormatterFactory`:运行时格式化器选择
## 安装
### 前置条件
- **.NET**: 10.0 SDK 或更高版本 ([下载](https://dotnet.microsoft.com/en-us/download))
- **操作系统**: Windows、macOS 或 Linux
- **终端**: PowerShell、Bash 或命令提示符
### 方法 1:克隆并构建
```
# Clone the repository
git clone https://github.com/sarmkadan/dotnet-source-generator-toolkit.git
cd dotnet-source-generator-toolkit
# Restore dependencies
dotnet restore
# Build the project
dotnet build -c Release
# Run tests (if available)
dotnet test
```
### 方法 2:直接运行(需要 .NET 10 SDK)
```
# Clone the repository
git clone https://github.com/sarmkadan/dotnet-source-generator-toolkit.git
cd dotnet-source-generator-toolkit
# Run directly without building
dotnet run -- [options]
```
### 方法 3:全局工具安装(推荐频繁使用)
```
# Pack as NuGet package
dotnet pack -c Release -o ./nupkg
# Install globally (requires private NuGet feed setup)
dotnet tool install --global DotNetSourceGeneratorToolkit --add-source ./nupkg
```
### 方法 4:Docker
```
# Build Docker image
docker build -t dotnet-source-generator-toolkit .
# Run in container
docker run --rm -v $(pwd):/workspace \
dotnet-source-generator-toolkit \
dotnet run -- /workspace
```
## 快速开始
### 1. 用属性标记您的实体
```
using DotNetSourceGeneratorToolkit.Domain;
namespace MyApp.Domain
{
[Repository]
[Mapper]
[Validator]
public class Product
{
public int Id { get; set; }
public string Name { get; set; } = string.Empty;
public string Description { get; set; } = string.Empty;
public decimal Price { get; set; }
public int StockQuantity { get; set; }
}
}
```
### 2. 运行工具包
```
# From your project directory
dotnet run -- --path . --format Json --output ./Generated
```
### 3. 生成的代码即可使用
```
// Generated repository
var repository = new ProductRepository(dbContext);
var products = await repository.GetAllAsync();
var product = await repository.FindByIdAsync(1);
// Generated mapper
var mapper = new ProductMapper();
var dto = mapper.MapToDto(product);
var entity = mapper.MapFromDto(dto);
// Generated validator
var validator = new ProductValidator();
var validationResult = await validator.ValidateAsync(product);
```
## 使用示例
### 示例 1:带有仓储生成的基本实体
```
// User.cs
[Repository]
public class User
{
public int Id { get; set; }
public string Email { get; set; } = string.Empty;
public string FirstName { get; set; } = string.Empty;
public string LastName { get; set; } = string.Empty;
public DateTime CreatedAt { get; set; } = DateTime.UtcNow;
}
// Generated code creates UserRepository with:
// - GetAllAsync()
// - GetByIdAsync(int id)
// - FindByEmailAsync(string email)
// - CreateAsync(User user)
// - UpdateAsync(User user)
// - DeleteAsync(int id)
// - GetPagedAsync(int pageNumber, int pageSize)
```
### 示例 2:使用配置进行 DTO 映射
```
// CustomerDto.cs
[Mapper(Profile = "ApiResponse")]
public class CustomerDto
{
public int Id { get; set; }
public string FullName { get; set; } = string.Empty;
public string Email { get; set; } = string.Empty;
}
// Customer.cs
[Mapper]
public class Customer
{
public int Id { get; set; }
public string FirstName { get; set; } = string.Empty;
public string LastName { get; set; } = string.Empty;
public string Email { get; set; } = string.Empty;
public string GetFullName() => $"{FirstName} {LastName}";
}
// Generated CustomerMapper handles:
// - Nested mapping (FirstName + LastName → FullName)
// - Bidirectional conversion
// - Null-safety checks
// - Collection mappings
```
### 示例 3:带有自定义规则的复杂验证器
```
[Validator(MessageLanguage = "en")]
public class OrderItem
{
public int ProductId { get; set; }
public int Quantity { get; set; }
public decimal UnitPrice { get; set; }
}
// Generated OrderItemValidator includes:
// - NotEmpty validation for ProductId
// - GreaterThan(0) for Quantity
// - PrecisionScale checks for UnitPrice
// - Custom async validation for stock availability
// - Localized error messages
```
### 示例 4:多格式序列化
```
[Serializer(Formats = new[] { "Json", "Xml", "Csv" })]
public class Report
{
public string Title { get; set; } = string.Empty;
public DateTime GeneratedAt { get; set; }
public List DataPoints { get; set; } = [];
}
// Generated serializers create:
// - JsonReportSerializer: JSON with custom naming
// - XmlReportSerializer: XML with schema
// - CsvReportSerializer: Spreadsheet format
// - BinaryReportSerializer: Compact binary format
```
### 示例 5:批量处理多个实体
```
# Process entire project directory
dotnet run -- --path ./MyProject \
--format Json \
--batch-size 10 \
--max-parallelism 4 \
--output ./Generated \
--backup-existing
# Monitor progress in real-time
dotnet run -- --path ./MyProject --verbose --log-level Trace
```
### 示例 6:Webhook 集成
```
// Configure in toolkit-config.json
{
"webhookEnabled": true,
"webhookUrl": "https://api.example.com/generation-complete",
"webhookRetries": 3,
"webhookTimeoutSeconds": 30
}
// Toolkit automatically POSTs generation results after completion
// Includes metadata: entity count, generation time, format, file paths
```
### 示例 7:自定义中间件集成
```
public class CustomMiddleware : IMiddleware
{
public async Task ExecuteAsync(
GenerationContext context,
Func next)
{
// Pre-processing
Console.WriteLine($"Starting generation for {context.EntityName}");
var startTime = DateTime.UtcNow;
await next(context);
var duration = DateTime.UtcNow - startTime;
// Post-processing
Console.WriteLine($"Completed in {duration.TotalSeconds}s");
}
}
```
### 示例 8:缓存生成的代码
```
// Automatic caching with configuration
{
"enableCaching": true,
"cacheExpirationMinutes": 60
}
// First run: generates and caches
dotnet run -- --path ./Project1
// Second run (within 60 min): serves from cache
dotnet run -- --path ./Project1
// Force cache refresh
dotnet run -- --path ./Project1 --clear-cache
```
### 示例 9:事件驱动架构
### 示例 10:指标收集和报告
```
var metricsCollector = provider.GetRequiredService();
// Toolkit automatically collects:
// - Generation time per entity
// - Cache hit rates
// - Output file sizes
// - Batch processing throughput
// - Error counts and types
var metrics = metricsCollector.GetMetrics();
Console.WriteLine($"Average generation time: {metrics.AverageGenerationTimeMs}ms");
Console.WriteLine($"Cache hit rate: {metrics.CacheHitRate:P}");
```
## API 参考
### 核心接口
#### `ISourceGeneratorService`
整个生成管道的主要编排服务。
```
public interface ISourceGeneratorService
{
// Analyzes a project directory and returns discovered entities
Task AnalyzeProjectAsync(string projectPath);
// Generates code for all discovered entities
Task
- > GenerateAllAsync(ProjectInfo projectInfo);
// Generates code for a specific entity
Task
- > GenerateAllAsync(List
- > GenerateAllMappersAsync(List
- > GenerateAllValidatorsAsync(List
标签:.NET开发, Roslyn, 代码生成, 存储库模式, 属性编程, 序列化器, 开发效率, 映射器, 样板代码, 渗透测试工具, 源代码生成器, 网络可观测性, 软件工具, 验证器