1
public class EnumDescriptionSchemaFilter : ISchemaFilter
2
{
3
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
4
    {
5
        if (context.Type.IsEnum)
6
        {
7
            schema.Enum.Clear();
8
            var enumDescriptions = new StringBuilder();
9

10
            foreach (var value in Enum.GetValues(context.Type))
11
            {
12
                var name = Enum.GetName(context.Type, value);
13
                var field = context.Type.GetField(name!);
14
                var descriptionAttr = field?.GetCustomAttribute<DescriptionAttribute>();
15
                var desc = descriptionAttr != null ? descriptionAttr.Description : name;
16

17
                schema.Enum.Add(new OpenApiString(name));
18
                enumDescriptions.AppendLine($"- `{Convert.ToInt64(value)}` = **{name}**: {desc}");
19
            }
20

21
            schema.Description += $"\n\n**可用枚举取值**：\n{enumDescriptions}";
22
        }
23
    }
24
}

1
builder.Services.AddSwaggerGen(c =>
2
{
3
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "工业物联网平台 API", Version = "v1" });
4

5
    // 1. 加载主工程与 DTO 库的 XML 注释
6
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
7
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
8
    if (File.Exists(xmlPath)) c.IncludeXmlComments(xmlPath);
9

10
    // 2. 注入枚举增强过滤器
11
    c.SchemaFilter<EnumDescriptionSchemaFilter>();
12
});

1
builder.Services.AddSwaggerGen(c =>
2
{
3
    // 配置 Bearer 授权方案
4
    var securityScheme = new OpenApiSecurityScheme
5
    {
6
        Name = "Authorization",
7
        Description = "请输入 JWT Bearer Token (格式: Bearer {token})",
8
        In = ParameterLocation.Header,
9
        Type = SecuritySchemeType.Http,
10
        Scheme = "bearer",
11
        BearerFormat = "JWT",
12
        Reference = new OpenApiReference
13
        {
14
            Type = ReferenceType.SecurityScheme,
15
            Id = "Bearer"
16
        }
17
    };
18

19
    c.AddSecurityDefinition("Bearer", securityScheme);
20
    c.AddSecurityRequirement(new OpenApiSecurityRequirement
21
    {
22
        { securityScheme, Array.Empty<string>() }
23
    });
24
});

1
flowchart LR
2
    Client[前端 Vue3/React] <-->|DTO 数据传输对象| Controller[Web API Controller]
3
    Controller <-->|Domain Logic| Service[应用与领域服务]
4
    Service <-->|Entity 数据库模型| DbContext[EF Core / 数据库]

1
// 1. 安装 Mapster.DependencyInjection
2
// 2. 编写轻量领域转换规则 (支持通用企业 ERP/电商订单与高精工控)
3
public class MappingRegister : IRegister
4
{
5
    public void Register(TypeAdapterConfig config)
6
    {
7
        // 通用企业级订单 DTO 映射 (计算总金额、脱敏手机号、映射状态文本)
8
        config.NewConfig<OrderEntity, OrderDetailDto>()
9
            .Map(dest => dest.StatusText, src => src.Status.ToString())
10
            .Map(dest => dest.CustomerMaskedPhone, src =>
11
                string.IsNullOrEmpty(src.CustomerPhone) ? "" :
12
                string.Concat(src.CustomerPhone.AsSpan(0, 3), "****", src.CustomerPhone.AsSpan(7)))
13
            .Map(dest => dest.ItemsCount, src => src.Items.Count)
14
            .Map(dest => dest.FormattedTotalAmount, src => $"¥{src.TotalAmount:N2}");
15
    }
16
}

1
[HttpGet("{id:guid}")]
2
public async Task<ActionResult<OrderDetailDto>> GetOrderById(Guid id, [FromServices] AppDbContext db)
3
{
4
    // 利用 ProjectToType 实现高效 SQL 投影查询 (仅从数据库 SELECT 目标列，避免全表宽列与关联大字段传输)
5
    var dto = await db.Orders
6
        .AsNoTracking()
7
        .Where(x => x.Id == id)
8
        .ProjectToType<OrderDetailDto>()
9
        .FirstOrDefaultAsync();
10

11
    return dto is null ? NotFound() : Ok(dto);
12
}

1
builder.Services.AddControllers()
2
    .AddJsonOptions(options =>
3
    {
4
        // 1. 采用小驼峰命名规范 (camelCase)
5
        options.JsonSerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase;
6

7
        // 2. 解决对象循环引用问题 (选择忽略循环节点)
8
        options.JsonSerializerOptions.ReferenceHandler = ReferenceHandler.IgnoreCycles;
9

10
        // 3. 支持字符串转数值等宽容模式 (防止前端将 "123" 作为 number 提交报错)
11
        options.JsonSerializerOptions.NumberHandling = JsonNumberHandling.AllowReadingFromString;
12

13
        // 4. 自定义 DateTime 序列化格式 (yyyy-MM-dd HH:mm:ss)
14
        options.JsonSerializerOptions.Converters.Add(new DateTimeJsonConverter("yyyy-MM-dd HH:mm:ss"));
15
    });

1
// 1. 定义 DTO 契约
2
public record DeviceTelemetryRecord(string DeviceId, double Voltage, double Current, DateTime Timestamp);
3

4
// 2. 声明源生成器上下文
5
[JsonSourceGenerationOptions(
6
    WriteIndented = false,
7
    PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase)]
8
[JsonSerializable(typeof(DeviceTelemetryRecord))]
9
[JsonSerializable(typeof(List<DeviceTelemetryRecord>))]
10
public partial class TelemetryJsonContext : JsonSerializerContext
11
{
12
}

1
app.MapPost("/api/telemetry", (DeviceTelemetryRecord data) =>
2
{
3
    // 底层直接利用静态生成的 TelemetryJsonContext 处理，毫无反射开销
4
    return Results.Ok(data);
5
}).WithSerializerOptions(TelemetryJsonContext.Default.Options);

1
// 传统自定义包装：
2
{
3
  "code": 200,
4
  "message": "success",
5
  "data": { ... }
6
}

1
public class GlobalExceptionHandler : IExceptionHandler
2
{
3
    private readonly IProblemDetailsService _problemDetailsService;
4
    private readonly ILogger<GlobalExceptionHandler> _logger;
5

6
    public GlobalExceptionHandler(
7
        IProblemDetailsService problemDetailsService,
8
        ILogger<GlobalExceptionHandler> logger)
9
    {
10
        _problemDetailsService = problemDetailsService;
11
        _logger = logger;
12
    }
13

14
    public async ValueTask<bool> TryHandleAsync(
15
        HttpContext httpContext,
16
        Exception exception,
17
        CancellationToken cancellationToken)
18
    {
19
        _logger.LogError(exception, "全局未捕获异常: {Message}", exception.Message);
20

21
        var (statusCode, title, errorCode) = exception switch
22
        {
23
            BusinessException bEx => (StatusCodes.Status400BadRequest, bEx.Message, bEx.ErrorCode),
24
            KeyNotFoundException => (StatusCodes.Status404NotFound, "请求的资源不存在", "ERR_NOT_FOUND"),
25
            UnauthorizedAccessException => (StatusCodes.Status403Forbidden, "当前操作未授权", "ERR_FORBIDDEN"),
26
            _ => (StatusCodes.Status500InternalServerError, "服务端内部未知故障", "ERR_INTERNAL_SERVER")
27
        };
28

29
        httpContext.Response.StatusCode = statusCode;
30

31
        // 利用官方 ProblemDetails 规范写入响应流
32
        var problemDetails = new ProblemDetails
33
        {
34
            Status = statusCode,
35
            Title = title,
36
            Detail = exception.Message,
37
            Instance = httpContext.Request.Path
38
        };
39
        problemDetails.Extensions["errorCode"] = errorCode;
40
        problemDetails.Extensions["traceId"] = httpContext.TraceIdentifier;
41

42
        return await _problemDetailsService.TryWriteAsync(new ProblemDetailsContext
43
        {
44
            HttpContext = httpContext,
45
            ProblemDetails = problemDetails,
46
            Exception = exception
47
        });
48
    }
49
}

1
builder.Services.AddProblemDetails(); // 注册 ProblemDetails 基础服务
2
builder.Services.AddExceptionHandler<GlobalExceptionHandler>(); // 注册全局处理器
3

4
var app = builder.Build();
5

6
app.UseExceptionHandler(); // 开启异常拦截管道
7
app.MapControllers();
8
app.Run();