C#类库选型与使用实践：从JSON到ORM的技术栈取舍

写了这么多年 C#，我越来越觉得，真正拉开项目差距的往往不是语言特性，而是“类库”这盘棋怎么下。一个功能，有人花两周从零实现，有人半天下班，区别就在会不会站在现成类库的肩膀上。C# 生态里的类库非常丰富，从 JSON 处理、日志记录、HTTP 请求，到对象映射、数据库访问、依赖注入，基本每种需求都有成熟的方案。但类库多也意味着选型难，很多人一开始贪多求全，结果项目被一堆第三方依赖拖得寸步难行。这里我想把自己的选型思路和使用经验整理出来，给正在搭项目或者准备重构的人一个参考。

1. 类库到底在解决什么问题

1.1 类库的本质是复用，不是炫技

类库本质上就是一段被反复验证过的代码，它把某类通用问题封装成公开 API，让使用者不需要关心底层是如何实现的。比如要把对象转成 JSON，自己写解析器要考虑字符串转义、日期格式、编码问题、循环引用，几天都未必写对；用成熟的 JSON 类库，一个方法调用就解决了。这个思维方式可以用开饭店来类比——你不会为了做一道菜从种菜开始，而是直接从靠谱供应商进货。类库就是你的供应商，它把食材处理好的同时，也要你接受它的供货周期和口味风格。

但这里有个关键：类库解决的是“通用问题”，不是“你的业务问题”。如果你用一个类库强行去封装特别个性化的业务逻辑，往往需要写大量配置和回调，反而比手写更复杂。我见过不少项目把简单代码包装成“万能类库”，结果每个调用点都得传十几个参数，谁看谁头疼。用类库的第一原则是：它应该让代码变简单，如果没变简单，就是在硬凑。

1.2 选型时我必看的四个维度

真正动手引入一个类库之前，我通常会做四件事，这里用一个表格列出来：

这四个维度不是平均用力。如果项目是内部工具，许可证可以宽松一些；如果是商业产品，许可证务必先看清。维护活跃度是最容易踩坑的，我看到过不少“功能完美但两年没更新”的库，一开始用得很爽，遇到运行时漏洞只能自己改源码。与其后面痛苦，不如一开始就选一个也许没那么花哨但一直有人的库。

1.3 显性成本和隐性成本都要算

引入类库的成本，很多时候被低估了。显性成本是下载、学习、调用，这个大家都会算。隐性成本才是真正的分水岭：升级时 API 可能不兼容、新版本可能引入安全漏洞、某一个传递依赖和现有库发生版本冲突、维护者突然弃坑。这些风险不会在引入的第一天爆发，但会在未来的某一天集中出现。

所以我经常用一个“替换测试”来评估一个类库：假设这个类库明天停更，我需要花多大代价把它换掉？如果答案是只改一个文件，说明这个库用得很健康；如果要改几十个业务类，说明它已经被深度耦合进系统。用类库时，心里始终要留一条“逃生通道”，这是后面分层设计的基础。

2. 高频类库的对比与使用

2.1 JSON 处理：内置方案与第三方方案怎么平衡

现代 .NET 项目里，JSON 处理的第一选择通常是 System.Text.Json。它是官方实现，性能好，依赖内建，API 也比较简洁。大多数场景下，我们只需要配置一下命名策略，就能把对象序列化成前端需要的格式：

using System.Text.Json; var payload = new { UserName = "test", Age = 30 }; var json = JsonSerializer.Serialize(payload, new JsonSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.CamelCase, WriteIndented = true }); Console.WriteLine(json);

这段代码会把 UserName 自动转成 userName，输出可读的 JSON 字符串。System.Text.Json 的优点是开箱即用，不需要额外引入包；缺点是它的一些扩展点和老牌 JSON 库不完全一样，比如自定义 Converter 的写法更繁琐，处理日期格式时选项没那么多。所以我保留一句话总结：新项目默认用 System.Text.Json，老项目如果已经大量使用另一个成熟 JSON 库，不要为了“统一”强制迁移。

很多老项目里代码已经深度依赖 JsonConvert，迁移成本极高，收益却不明显。如果必须让两种 JSON 库同时存在，尽量通过数据契约来隔离，比如在 DTO 层定义明确的 JSON 特性，而不是让两个库随意处理同一个对象。我实际见过一个项目把同一个实体类同时交给两个序列化库处理，日期格式一个输出成数组，一个输出成字符串，前端兼容起来非常痛苦。

2.2 日志：先定好日志抽象，再选具体实现

日志这块我见过太多项目把它做成了灾难。最常见的错误是直接在业务代码里 new 一个静态日志对象，然后到处调用。这样做的结果就是：改日志配置需要改一堆文件，测试环境控制台可能没有输出，生产环境又不方便查文件。正确做法是依赖抽象，比如 ASP.NET Core 的 ILogger ：

public class OrderService { private readonly ILogger<OrderService> _logger; public OrderService(ILogger<OrderService> logger) { _logger = logger; } public async Task CreateAsync(Order order) { _logger.LogInformation("创建订单 {OrderId}，金额 {Amount}", order.Id, order.Amount); } }

这里有两个细节值得注意。第一，日志消息不要用字符串拼接，要写结构化模板，把参数放在后面。后面的日志系统可以按 OrderId、Amount 做索引检索，排查问题会快很多。第二，构造函数注入的 ILogger 里，T 代表当前类，日志会自动带上类名，方便定位。

如果要引入第三方日志库做文件输出或集中收集，我一般选择 Serilog 这类成熟方案。它最大的优势是用配置文件就能完成大部分设置，而且和 ILogger 无缝集成。配置示例：

{ "Serilog": { "MinimumLevel": "Information", "WriteTo": [ { "Name": "Console" }, { "Name": "File", "Args": { "path": "logs/app-.log", "rollingInterval": "Day" } } ] } }

配置完成后，启动时只需要一句 builder.Host.UseSerilog()，所有 ILogger 输出都会落到配置目标。踩过的坑是：日志配置文件经常因为“复制到输出目录”没设置而找不到，或者启动时日志初始化失败让服务直接退出。我的习惯是让日志系统在启动阶段具备“最后保底”能力，比如控制台输出默认开着，文件没了不影响进程起来。

2.3 对象映射：少写重复赋值代码，但别滥用

业务项目里最常见的就是各种模型之间互转，实体转 DTO、DTO 转视图模型，字段长得差不多，手写赋值非常枯燥，而且漏写字段可能需要很久才暴露。对象映射类库就是解决这个问题的。Mapster 是一个我很喜欢的轻量方案，大部分场景不需要预先配置：

var userDto = user.Adapt<UserDto>();

一句话就能完成映射。如果要自定义字段名，可以在 Adapt 的时候传入配置，也可以建一个映射配置类。相比之下，AutoMapper 功能更重，需要先声明映射关系然后由容器创建 mapper 实例，适合团队中已经有约定和大量规则的情况：

var config = new MapperConfiguration(cfg => cfg.CreateMap<User, UserDto>()); var mapper = config.CreateMapper(); var userDto = mapper.Map<UserDto>(user);

我的经验是：简单映射直接写 DTO 构造函数或者用 Mapster 就够了，别动不动引入映射框架。真正复杂、字段名不一样、需要做值计算的逻辑，手写扩展方法反而更清楚。映射框架最怕的就是在项目里“隐形地”改掉了字段默认行为，让后来的维护者对着输出结果一脸懵。越是复杂的映射，越应该显式写清楚，因为它本质上就是业务规则的一部分。

2.4 HTTP 通信：HttpClient 的正确姿势

在微服务、接口对接场景里，HTTP 调用是绕不开的。很多人第一个想法是 new HttpClient，然后到处调用。这其实是个隐患，因为 HttpClient 在频繁创建和销毁时可能会耗尽底层连接资源。这边建议使用 IHttpClientFactory，它帮你管理连接生命周期，还能集中配置基础地址、超时时间、默认请求头。注册方式很简单：

builder.Services.AddHttpClient("api", client => { client.BaseAddress = new Uri("https://api.example.com"); client.Timeout = TimeSpan.FromSeconds(10); });

然后在业务类里通过注入的 IHttpClientFactory 创建具名客户端。更进一步，可以用 Refit 把 HTTP 接口声明式地定义成 C# 接口，避免手写一堆请求参数拼装代码。例如：

public interface IUserApi { [Get("/users/{id}")] Task<UserDto> GetUserAsync(string id, CancellationToken ct); }

之后用 AddRefitClient 注册，整个服务里只需要注入 IUserApi 就行。接口方法上的路由模板、HTTP 谓词一目了然，也方便做单元测试。这里要特别提醒：外部 HTTP 调用一定要有超时和重试策略。超时可以靠 Timeout，重试可以用 Polly。但重试不能无脑套，对 POST、PUT 这类可能改变服务端状态的接口，重试前要评估幂等性，否则一个临时网络抖动可能让用户收到重复的提示。我现在习惯是只对 GET 或带幂等键的请求配置自动重试，其余接口宁可做个友好的失败提示，也不盲目重试。

2.5 数据访问：ORM 和原生 SQL 之间要有分寸

数据访问类库是所有选择里影响最深的，因为业务核心都围绕数据在转。EF Core 是官方推荐的 ORM，模型驱动，支持迁移，用 Linq 写查询很舒服。Dapper 是轻量级的思路，你要自己写 SQL，然后把结果映射到模型。两者没有绝对优劣，看场景：

实际项目里我倾向于混用。主体领域模型、增删改查、事务这些用 EF Core，让代码结构清晰、迁移可控；报表、统计、复杂联表查询用 Dapper，直接写优化的 SQL，性能更好。Dapper 的用法也比较简洁：

using var connection = new SqlConnection(connectionString); var user = await connection.QueryFirstOrDefaultAsync<User>( "SELECT * FROM Users WHERE Id = @Id", new { Id = userId });

混用的前提是划分边界。不要在业务服务里一会儿注入 EF 的 DbContext，一会儿又直接用 DbConnection，那样会让事务和缓存很难管理。我会在基础设施层定义仓储接口，业务层只面向接口，具体是 EF 实现还是 Dapper 实现，对上层不可见。这样两种方式可以共存，也不会污染业务代码。

2.6 依赖注入：内置容器其实比很多人想的强

依赖注入已经成为现代 C# 应用的基础能力。ASP.NET Core 内置容器支持构造函数注入、生命周期管理和服务批量注册，绝大多数项目不需要额外引入第三方容器。很多团队一上来就引入第三方容器，可能是被老资料影响了，或者想用属性注入、拦截能力，但引入第三方容器是有代价的：启动配置复杂、团队成员学习成本增加。

那什么时候需要第三方容器？我的经验是：当你需要基于约定批量注册程序集，或者插件系统要求动态加载模块时，第三方容器提供的一些按程序集扫描注册的功能会非常方便。如果你只是为 Controller 和 Service 做普通注册，内置容器完全够用。判断标准很简单：你的依赖注入需求是否超出了“构造函数注入”和“单例/作用域/瞬时”这三板斧。没有超出，就用内置，省心且不容易出问题。

3. 类库分层设计与依赖组织

3.1 三类类库：框架类、工具类、基础设施类

你用到的各种类库，可以粗略分成三类。框架类类库和你选的架构直接绑定，比如 Web 框架、ORM、服务框架，这类库一旦深度使用，替换成本很大。工具类类库解决通用问题，比如 JSON、映射、字符串处理，它们是纯功能性代码，和外部环境无关，替换成本低。基础设施类类库负责和外部系统交互，比如 HTTP 客户端库、缓存客户端、消息队列客户端，它们通常需要配置连接信息，替换成本取决于封装层做得好不好。

记清这个分类有什么用？它决定了你在层级设计里要怎么放这些依赖。框架类类库应该集中收敛在基础设施层，不要让每一个业务类直接依赖具体 ORM 的实体类；工具类类库可以在各个层使用，因为它们无状态、纯函数；基础设施类类库最好被包装成服务接口，让业务层只面向接口。这个意识能大大降低后续重构的痛感。

3.2 给第三方依赖加一道“保命接口”

我常用的一种做法是：对容易变化的第三方依赖，定义自己的接口，然后写一个实现类。比如缓存，先定义：

public interface ICacheService { Task<T?> GetAsync<T>(string key, CancellationToken ct); Task SetAsync<T>(string key, T value, TimeSpan expiry, CancellationToken ct); }

然后底层用内存缓存或者 Redis 客户端去实现。业务层只引用 ICacheService，具体缓存类库只出现在实现这个接口的项目里。以后从单机内存换成 Redis 集群，或者从库 A 换到库 B，需要改的只是实现类，而不是满世界找业务代码里的直接调用。

但不是所有依赖都值得包这一层。比如 JSON 序列化，它本身就是一个通用的静态工具，没有外部环境变化，你再包一层反而增加无谓的抽象。所以我的原则是：可能变化、涉及 IO、需要资源隔离的依赖，必须包边界；纯计算、无状态的依赖，直接用没关系。

3.3 一个典型的项目依赖方向

结合上面的原则，我习惯的项目结构是这样的：

• 表示层：负责接口、模型绑定、输出格式，不直接依赖具体 ORM 和日志库。
• 应用层：处理用例、定义接口、使用工具类进行模型转换，依赖日志抽象但不依赖具体日志库。
• 基础设施层：实现应用层定义的接口，使用具体的数据访问、缓存、外部 HTTP 客户端类库。

这样依赖方向从外层指向内层，基础设施在最底部，业务核心在最中间。如果有人问要不要在表示层直接访问 Dapper，答案是否定的。让业务脱离具体类库的束缚，才敢在整个系统里大胆换库、升级库。

4. 常见坑与排查技巧

4.1 版本冲突：最让人抓狂的传递依赖

C# 项目里最常遇到的问题就是“程序集版本冲突”。表面上 A 库用 X 类库 1.0，B 库用 X 类库 2.0，编译时一切正常，运行时直接报“未能加载文件或程序集”。因为传递依赖会把两个版本都带进来，而运行时不知道用哪个。遇到这类问题，第一步不要盲目删包，先看项目生成的 deps.json 文件中 X 类的引用框架，再开启动程序集绑定日志看实际加载路径。

我自己的排查习惯是打开启动日志中的模块解析日志，查看程序集绑定失败原因，确认是版本问题还是路径问题。能通过在现有项目里统一升级到兼容版本来解决，就尽量升级，而不是用绑定重定向强压，因为强压一段时间后会把问题藏得更深，等真正出问题的时候反而无从下手。

4.2 循环引用：序列化时的连环爆

实体对象之间常有导航属性互相引用，比如订单引用用户，用户又引用订单列表。把这些对象直接序列化给前端时，序列化库会顺着引用链路一直往下走，轻则抛异常，重则占用大量内存。System.Text.Json 默认对检测到的循环引用会直接报错，另一部分老牌 JSON 库则可以通过选项忽略某些引用。但在我看来，这都是治标不治本。

治本的办法是：不要让实体对象直接参与输出，专门定义 DTO。DTO 只包含你需要展示的字段，循环关系天然被切断了。比如订单 DTO 只包含用户名，不包含用户下的订单列表。这不仅是序列化问题，也是接口设计问题，效果比任何序列化配置都好。

4.3 日志不输出，先检查配置文件

日志类库的坑通常很直接，服务跑起来但日志文件没生成。原因多半是配置文件没被复制到输出目录，或者路径写的是相对路径但启动工作目录不对。遇到日志异常，我不会先怀疑代码，而是先确认配置文件和运行目录。另一个常见问题是日志输出到控制台很流畅，一旦切到文件就什么都没有，这时要检查文件滚动策略和日志级别是否把 Information 级别给过滤掉了。

4.4 类库升级：先跑兼容性测试再上主干

第三方类库升级不能只看大版本号。有时候只是升一个小版本，行为都可能变化。注意官方不一定会在更新日志里标注所有的破坏性变更。我养成一个习惯：每个季度集中评估一次在用类库的更新，把新版本放到单独的升级分支，先运行所有单元测试和集成测试，再手动跑一遍核心流程，确认没问题再合并主干。

如果项目没有自动测试，类库升级就变得更加危险。所以哪怕业务压力再大，也要为核心链路保留一套冒烟测试。没有测试保护的升级，就是在用线上事故赌运气，这一点我吃过不少亏。

4.5 警惕“类库绑架”效应

有些类库本身很好，但如果你使用了它的特殊高级特性，就可能被它绑架。比如某个类库支持 AOP 拦截，你到处用它，后来想把底层实现换成别的，发现所有业务逻辑都和这个类库的 API 绑定了。为了避免这种情况，核心业务代码里尽量只用类库最基础、最通用的 API，高级特性放在基础设施层。用“最少但够用”的方式去使用一个类库，是降低耦合的有效手段。

5. 不同项目规模下的类库清单

5.1 小工具与脚本类项目

如果你是写一个小工具、控制台任务或者快速原型，不需要太重。JSON 用 System.Text.Json，日志用控制台输出就好，数据访问简单的话直接用 Dapper 加原生的连接字符串，依赖注入可以完全省略，手动 new 几个服务就行。这种项目核心是快，不要为了“架构”引入一堆没必要的类库。

5.2 Web API 服务

常规 Web API 项目，我一般这样选型：序列化用 System.Text.Json；日志用 Serilog 或者内置 ILogger 加结构化模板；数据访问主体用 EF Core，报表查询用 Dapper；HTTP 外部调用用 IHttpClientFactory 加 Refit；对象映射用 Mapster；缓存自己抽象一层。这套组合足够应对大部分业务系统，而且每块都被社区验证过。

5.3 微服务和分布式系统

微服务场景里，类库选型会更加谨慎。服务注册发现、配置中心、消息队列这些基础设施依赖，要先确认好平台和运维能力再定；可观测性方面，结构化日志、调用链追踪、指标采集三个方向都要有对应类库。这个阶段不要自己造轮子，尽量用已经在团队里打通过流程的类库，减少每个服务各自为政。不同服务之间的类库版本可以错开，但基础组件版本要尽量对齐，否则全局升级时会很痛苦。

6. 关于类库，我最后想说的几句话

6.1 引入前做一个“最小验证”

不要因为一个类库文档写得好就立刻引入。先花半小时写一个 Demo，放在你自己的项目上下文里跑一遍，看 API 是不是顺手，配置是不是能看懂。很多时候“看着好”和“用着好”是两回事，Demo 会告诉你真实感受。

6.2 可替换性比功能全面更重要

我见过太多项目为了用某个类库的一个功能，不得不忍受它一堆不方便的设计。其实你可以换个角度：哪个类库离你的核心逻辑更远，能轻松替换？好的类库使用方式应该让业务代码看不出它在用这些库。如果类库功能少了，你还可以扩展；如果类库已经焊死在业务代码里，就真的只能一条路走到黑了。

6.3 自己动手维护一个类库清单

每个团队都值得维护一份类库清单，记录每个类库解决什么问题、当前版本、升级时间、为什么选它。这个文档不需要多长，但能在架构评审和新人入职时省下大量时间。我也建议定期检查一次版本和社区活跃度，把已经停止维护的库标记出来，提前规划替换方案。

写到这儿，也没有一个放之四海而皆准的“最佳类库列表”。类库的选择取决于你的场景、团队、运维能力和契约边界。我个人在实际操作中的体会就是：类库不是越多越好，而是越准确越好；不是越流行越好，而是越容易替换越好。把这两条思路带到选型现场，很多纠结会自然消失。