用C#写后端项目ORM选型是个绕不开的话题。EF Core功能全但偏重Dapper灵活但开发效率低SqlSugar算是中间路线既有实体映射、CodeFirst、仓储封装这些高亮功能又保留着接近SQL的手感。这两年我在好几个MySQL项目里稳定用它整体很顺手但过程中也踩了不少坑。有些问题不是SqlSugar本身的bug而是C#和MySQL两套体系碰撞出的摩擦——连接串里一行配置不对、时间字段悄悄变了、批量插入速度上不去、事务把连接池堵死了、实体类字段和表列名对不上……这类问题一旦遇到排查起来非常费时间。这篇文章我想把C# SqlSugar MySQL这个组合下最容易忽略的5个细节拉出来聊聊基本都是实际项目里踩过、修过、后来总结成规范的点。不管你是刚上手SqlSugar的新人还是已经在生产环境里跑了一段时间的老手这几个地方都值得对一遍。有的坑属于配置层面有的属于写法问题还有的是两个生态之间的概念差异按顺序处理完能给后续开发省下大量反复试错的时间。1. 选型思路为什么是SqlSugar加MySQL1.1 这套组合解决什么问题先说结论SqlSugar搭配MySQL特别适合中小型业务系统、内部管理系统、上位机数据采集这类项目。这类项目的共同点是表结构不算特别复杂、读写比例明确、开发周期紧、团队不一定有专职DBA。SqlSugar在这个场景下优势非常明显它比EF Core轻不需要维护庞大的迁移历史也比Dapper省心不用自己写一堆仓储和映射代码。再加上它对MySQL的适配做得很细从建库建表到查询分页都有现成封装基本能在半天内跑通数据访问层。MySQL这边则是另一个逻辑。它足够普及部署成本低社区资料多遇到问题随便一搜就有答案。C#开发者常用的SQL Server在中小项目里部署成本偏高而PostgreSQL虽然也很强但团队熟悉度往往不如MySQL。两者结合SqlSugar负责把C#的强类型语言特性和SQL梳理成一条清晰的通道MySQL负责稳定存住数据配合得很舒服。1.2 先理清版本对应关系很多坑其实源于版本不匹配。你的项目如果是.NET 6以上的建议直接用SqlSugarCore如果是.NET Framework 4.x的老项目用SqlSugar的Framework版本。不同版本的API签名虽然大体一致但底层驱动处理方式有差异。我见过有人在.NET Framework 4.5项目里引了SqlSugarCore的包编译时各种报错花了一晚上才发现是包选错了。MySQL这边也一样MySQL 5.7和MySQL 8.0在认证插件、JSON类型支持、排序规则上都有差异SqlSugar对不同MySQL版本的适配逻辑也不同。我的建议是新的项目直接用MySQL 8.0以上SqlSugar版本尽量保持最新稳定版。这样默认的加密规则、JSON列映射、索引提示等功能都能正常用不用为了兼容老特性牺牲新能力。提示NuGet包的版本不要追太新的预览版选最新的正式发布版。预览版虽然后台跑通不少但到了生产环境碰到的边界情况经常不是文档里能查到的。2. 第一个细节连接字符串配置错一行就白折腾2.1 一份能跑的MySQL连接串到底长什么样先给一份我项目里在用的标准连接串模板Server127.0.0.1;Port3306;Databaseyour_db;Uidyour_user;Pwdyour_password;CharSetutf8mb4;SslModeNone;AllowPublicKeyRetrievalTrue;Connection Timeout10;PoolingTrue;Max Pool Size100;这里有几个值要特别注意。CharSetutf8mb4这一段是最容易被坑的。很多教程里写的是utf8但你如果存的用户昵称或评论内容里有emoji字符utf8编码在MySQL里根本存不下写入直接报错或者变成一串问号。utf8mb4才是MySQL里正儿八经的完整UTF-8支持。MySQL 8.0默认字符集虽然是utf8mb4但连接层面的字符集还是会受连接串影响所以这行必须写清楚。SslModeNone要特别说明。本地开发环境如果MySQL没有配置SSL证书SslMode保持默认可能连接直接报SSL错误。我在没有打开任何SSL选项的MySQL 5.7上就遇到过这个问题后来在连接串里显式加上SslModeNone才连上。生产环境如果确实需要SSL务必让DBA把证书配置好再用SslModeRequired开启。AllowPublicKeyRetrievalTrue是MySQL 8.0时代的特殊配置。8.0默认用caching_sha2_password作为认证插件客户端第一次连接时需要从服务端获取公钥来加密密码传输。如果这个开关不打开连接会报Authentication method caching_sha2_password not supported。安全性上要考虑一下但这个开关在大多数内网场景下是可以接受的。2.2 驱动选择MySql.Data还是MySqlConnectorSqlSugar在底层封装了MySQL驱动但实际干活的是MySql.Data或者MySqlConnector这个类库。很多人在NuGet里装SqlSugarCore之后发现连不上MySQL第一反应是配置写错了其实多半是驱动缺了。SqlSugarCore默认依赖MySqlConnector不过也有版本差异。我的建议是用MySqlConnector。原因有两个一是它性能更好二是它持续维护对MySQL 8.0的协议支持更完整。你只需要在NuGet里同时安装SqlSugarCore和MySqlConnector即可SqlSugar会自动识别并调用。如果你之前装了MySql.Data建议先卸载避免两个驱动同时存在导致的类型冲突。注意项目里同时引用了MySql.Data和MySqlConnector有时不会直接编译报错但运行时会抛出类似Type MySqlConnection exists in both...的异常。排查起来很烦干脆从一开始就固定一个驱动。2.3 连接池参数怎么给才合理连接池是SqlSugar底层自动帮忙管理的但参数设置直接影响高并发表现。PoolingTrue开启连接池Max Pool Size100指最大连接数。内网应用100基本够用但如果你的服务并发峰值很高或者数据库是低配云主机100个连接可能直接压垮MySQL。我处理过一个案例某个定时任务集群同时跑20个实例每个实例开20个连接做批量处理直接把数据库的连接数打满其他业务全部超时。后来把Max Pool Size调小并且让连接用完立即释放问题才缓解。Connection Timeout10是连接超时时间单位秒。内网环境10秒绰绰有余公网环境建议设为30秒因为网络抖动可能导致连接握手超时。但这个值不能设太大否则数据库不可用时业务线程会长时间阻塞故障恢复时间被拉得很长。还有一个隐藏参数是Minimum Pool Size也就是最小连接数。如果你的服务启动时有冷启动延迟问题可以在连接串里加上Minimum Pool Size5让应用启动时立即建立预连接避免第一个请求进来时才去建连接。不过连接池本质上是按需创建的这一项通常是锦上添花。3. 第二个细节批量插入没跑起来代码写得再漂亮也没用3.1 Insertable是伪批量用SqlSugar插入列表数据最自然的写法是这样var list new ListOrder(); // ...填充list var count db.Insertable(list).ExecuteCommand();这段代码在你的list只有几条、几十条时完全没问题。但list一旦到几百、上千问题就来了——SqlSugar默认情况下是把列表拆成一条一条的INSERT语句逐条执行或者拼接成一个大VALUES块。前者性能差后者可能超过MySQL允许的包大小上限。你可能会说SqlSugar明明有批量插入的接口。但这里的批量本质上是减少了C#侧的循环调用底层仍然没有用MySQL真正高效的批量写入协议。MySQL真正的批量插入是MySqlBulkCopy原理是基于LOAD DATA这类的底层协议一次性把数据灌进去速度能比逐条插入快两个数量级。3.2 真正的大批量方案BulkCopySqlSugar从某个版本开始提供了DbFastest专门用于绕过传统Insertable的高性能写入var list new ListOrder(); // ...填充大量数据 db.FastestOrder().BulkCopy(list);这个API内部会走MySqlBulkCopy的路径。我用10万条数据做过对比逐条Insertable大概需要几十秒甚至更久使用BulkCopy后通常在1到2秒内完成差距非常明显。如果做数据迁移、日志灌库、报表数据导入这类场景几乎可以无脑选BulkCopy。但BulkCopy不是没有代价。它默认不返回自增主键也就是说批量插完之后你拿不到这堆数据的自增ID。如果你后续逻辑需要这些ID就得在插入之前用业务单据号或者GUID做关联要么在插入后重新查一次。另外BulkCopy对数据行的列顺序敏感如果实体属性和表列顺序出入较大建议用SqlSugar提供的列映射配置把属性名和列名对齐。3.3 大批量写入的参数调优跑BulkCopy的时候最常遇见的报错是MySqlException: Packets larger than max_allowed_packet are not allowed.这是MySQL服务端的max_allowed_packet参数设小了。默认值一般只有4MB大批量数据一个数据包就超了。处理方式分两步一是尽量分批灌比如每批5万条二是调整MySQL服务端的max_allowed_packet到64MB或128MB同时把连接串里的max_allowed_packet也加上。注意这两个地方都得改只改一端不生效。分批灌的时候批次大小不是越大越好。批太大内存占用高网络包容易超限批太小又发挥不出BulkCopy的优势。我的经验是5万到10万条一批比较稳妥字段少可以往上走字段多就往下调。如果单条记录非常大比如有BLOB字段控制在1万条一批更安全。还有一个容易忽略的点BulkCopy之前如果实体类里有数据列没有赋值MySqlBulkCopy会把默认值写进表里但这个默认值可能不是你想要的。执行前要做一次合法性检查比如List去掉空项、必填字段做非空校验。4. 第三个细节时间字段的时区与零点问题4.1 取出来的时间少了8小时C#的DateTime和MySQL的时间类型本身都是日期时间但连接字符串、驱动版本、MySQL时区这三方只要有一个不一致就会出现时间偏移。最典型的症状是明明数据库里存的是2025-01-15 10:30:00用SqlSugar查出来C#里却变成2025-01-15 02:30:00或者反过来写入时多了8小时。产生这个问题的原因是MySQL连接层和.Net驱动默认按本地时区解析时间。如果你的应用服务器设置了UTC时区而MySQL数据库设置的是东八区两者一换算就把时间拉偏了。解决思路是统一时区基准。我现在的做法是MySQL连接串里不显式配置Connection Timezone而是把应用服务器和MySQL服务器的系统时区都设为同一个时区国内业务就用Asia/Shanghai连接串里的CharSet和时区相关选项保持简单默认。如果必须使用UTC存储那就在所有地方都用UTC服务器时区、连接串、C#代码里读写都显式用DateTime.UtcNow展示的时候再转本地时间。4.2 DateTime.MinValue和数据库里的0000-00-00另一个更隐蔽的坑是MySQL允许存0000-00-00 00:00:00这个特殊时间值但C#的DateTime类型不支持。当你用SqlSugar查询某一行数据这个字段在数据库里是0000-00-00 00:00:00时映射到DateTime就会抛异常或者返回一个奇怪的默认值。很多老系统在业务上习惯用这个值表示没有时间但在C#里这行数据根本读取不了。我处理这个问题的方案是建表时统一约定时间字段不存0000-00-00不存在就用NULLC#侧用DateTime?映射。如果老表已经有这种脏数据可以写一个迁移SQL把这些值统一改成NULL。Sqlsugar的实体属性对应改成public DateTime? UpdateTime { get; set; }这样查询就不会因为空日期而崩溃。注意DateTime? 在SqlSugar的ORM映射里是支持很好的不要因为老代码习惯了非空类型就不敢用可空类型。该用就用。4.3 统一时间处理方案踩了几次时间的坑之后我定了一个规矩数据库里所有时间字段统一用datetime类型C#实体统一用DateTime或DateTime?不混用timestamp。timestamp这个类型有2038年问题而且会随MySQL时区设置自动转换很容易引入隐藏bug。datetime不会自动转换你存什么就是什么反而可控。还建议在SqlSugar全局配置里统一处理一下时间格式尤其是在做JSON序列化输出给前端的时候。C#的DateTime默认序列化出来是2025-01-15T10:30:00这种格式前端经常要的是2025-01-15 10:30:00。在项目启动时加上全局配置序列化时统一格式化避免每个接口都写一行转换逻辑。5. 第四个细节事务、异步方法用不好会把数据库堵死5.1 事务必须和同一个Db实例绑定SqlSugar的事务定义很好用但前提是你必须理解它的事务机制开事务、提交事务、回滚事务三者必须发生在同一个SqlSugarScope实例上。try { db.BeginTran(); db.Insertable(order).ExecuteCommand(); db.Updateable(orderDetail).ExecuteCommand(); db.CommitTran(); } catch { db.RollbackTran(); }这段代码看起来没问题。但如果你的代码里用了依赖注入每个方法都从容器里取一个新的SqlSugarScope而你在方法A里开了事务又跑到方法B里去执行数据操作B用的是另一个实例B里的操作就不受这个事务保护。等A提交的时候B的数据早就独立写入或者还在连接池里悬着整个事务就是形同虚设。解决方案事务范围内的所有数据库操作必须共享同一个SqlSugarScope实例。在Web项目中我建议每个请求级别注册一个作用域Scoped整个请求链路上的所有Repository都从当前请求作用域里拿同一个实例。这样做事务控制会自然很多。5.2 异步混用会导致连接池耗尽SqlSugar提供了完整的异步方法比如InsertableAsync、ExecuteCommandAsync。如果你的业务方法已经用了async/await那数据库操作最好全部用异步版本。我见过不少项目方法签名是async Task里面调用数据库操作却用同步的ExecuteCommand这在低并发下没什么一遇到高峰就出问题。逻辑是这样的异步方法里调用同步阻塞的数据库操作当前线程会一直占着不释放而asp.net core在高并发下线程池是有限资源。当大量请求都在这么干线程池会被占满后续请求排队数据库连接池也被占满最终表现为应用假死、请求超时。所以全链路异步是必须的。方法名命名也建议带上Async后缀从这个层面逼自己保持一致。5.3 嵌套事务与隔离级别SqlSugar对嵌套事务的支持简单直接你如果在一个已开启事务的实例上再次调用BeginTran会根据配置抛错或直接覆盖。我建议在项目里封装一个简单的事务工具类尽量避免业务代码里手动嵌套。隔离级别也是容易被跳过的一环。MySQL的默认隔离级别是REPEATABLE READ在某些场景下会出现幻读和间隙锁问题。比如定时任务里先查出一批未处理的订单然后逐个处理更新。如果多个任务实例同时跑REPEATABLE READ会导致每个实例都查到同样的数据然后互相更新覆盖。这种情况要么用分布式锁保证任务唯一要么在事务里显式改成READ COMMITTEDSqlSugar支持db.Ado.BeginTran(IsolationLevel.ReadCommitted)。高并发写场景下REPEATABLE READ容易引发死锁MySQL的InnoDB引擎会回滚其中一个事务程序里偶尔报死锁错误。如果业务允许建议把隔离级别调成READ COMMITTED并发写入的体验会平滑很多。6. 第五个细节实体映射最容易被忽略的命名拉锯战6.1 列名映射的三种方案C#属性命名惯例是PascalCase比如UserName、OrderNumber。MySQL的命名习惯一般是下划线比如user_name、order_number。虽然MySQL字段也支持大小写混合但Windows开发环境下MySQL的表和字段名大小写不敏感部署到Linux上就敏感这个差异能让同一套代码在不同环境上表现完全不同。所以规范的做法是MySQL表结构统一用下划线命名C#实体统一用PascalCase中间靠映射转换。SqlSugar里最直观的做法是给属性加特性[SugarColumn(ColumnName user_name)] public string UserName { get; set; }但一个项目几十张表每张表十几个字段全加特性显得很啰嗦。SqlSugar提供了全局的下划线映射开关可以自动把实体属性名转成下划线风格去匹配数据库列名。开启后UserName自动对应user_name不需要每个属性都手写特性。这个配置放在项目初始化时db.DbMaintenance ... // 或者使用ConfigureExternalServices里的EntityService具体用哪种方式取决于你的项目阶段。老项目表结构已经固定推荐显式写特性可读性强、可维护新项目从零开发直接开启全局下划线转换代码干净很多。6.2 数据类型映射的边界情况C#和MySQL的类型映射也有几个容易翻车的边界情况。bool型在MySQL里常用tinyint(1)存储SqlSugar默认能把C#的bool转成tinyint(1)但如果字段定义是bit在某些版本组合下又会出问题。我的建议是统一用tinyint(1)存布尔值尽量避免bit省得排查一个0和1的问题。decimal类型要注意精度。C#的decimal默认精度和默认保留位数不能直接映射到MySQL的decimal(M,D)SqlSugar建表时如果没显式指定可能建出来的列精度不够。高精度计算比如金额、单价必须在实体特性里指定[SugarColumn(DecimalDigits 2, Length 10)] public decimal Amount { get; set; }string类型也要注意长度。SqlSugar CodeFirst建表时字符串默认长度可能是255如果你的业务字段明显要存很长的文本比如备注、详情描述必须显式指定Length或者用string和SqlSugar的ColumnDataType text来定义。6.3 CodeFirst建表的默认值陷阱SqlSugar的CodeFirst用起来非常爽实体类定义好运行程序数据库表就自动建好了。但这个爽背后藏着几个默认值陷阱。第一个是字符串类型的默认列排序规则。MySQL建表时如果没指定会用数据库级别的排序规则。如果你的数据库默认排序规则是utf8mb4_general_ci大小写不敏感而你恰恰有个字段要区分大小写那查询就会出问题。解决方式是在实体特性里给特定字段指定排序规则。第二个是更新时间字段。很多表需要一个update_time字段每次更新时自动刷新。SqlSugar的实体里可以通过特性配置IsOnlyIgnoreInsert或使用数据库端DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP来生成但如果你在C#实体里用了默认值反而可能覆盖掉数据库的自动更新逻辑导致时间不更新。建议这类字段在数据库端建表时处理好然后在C#实体里标注只读或忽略插入更新。7. 避坑速查表与我的实操心得7.1 这个组合里最常见的报错和处理方式报错信息原因处理方式Authentication method caching_sha2_password not supportedMySQL 8.0认证插件与驱动不匹配连接串加AllowPublicKeyRetrievalTrue或升级驱动Packets larger than max_allowed_packet批量插入数据包超过MySQL限制调整max_allowed_packet分批插入Timeout expired连接池耗尽或SQL执行超时调连接池大小、优化SQL、检查是否有事务未提交DateTime in unrepresentable range数据库字段为0000-00-00 00:00:00字段改为可空DateTime?清理脏数据Column xx cannot be nullC#侧没有给必填字段赋值插入前做数据校验不要把默认值寄托给数据库Duplicate entry xx for key xx唯一索引冲突预先判断数据是否存在或捕获异常做业务补偿这六个报错我几乎每个项目都遇到过尤其是前三个出现的概率非常高。排查出来之后不要只改代码最好在团队的开发规范里写明对应的连接串模板和使用约定从源头上让后面接入的同事少踩一遍。7.2 我习惯坚持的几个小规范第一个规范是连接串集中管理不要散落得到处都是。用ConfigurationManager或Options模式统一配置不同环境开发、测试、生产切换时只改一个入口避免有人在自己机器上改了连接串提交上去把测试库和开发库搞得一团糟。第二个规范是实体类的字段和数据库列名全部走全局下划线映射。这个不一定适合所有项目但对新项目来说收益很大。代码里全是UserName这种原生C#风格数据库全是user_name这种SQL风格两边读代码都顺畅。第三个规范是批量操作前必看数据量。几千条以内随便Insertable超过一万条必须考虑BulkCopy超过十万条不仅要BulkCopy还要强制分批加事务控制。这个阈值放在团队规范里能挡住很多性能事故。第四个规范是事务操作必须封装开不让业务代码直接裸调BeginTran。做一个简单的事务工具类传入接收Db对象的业务委托内部统一处理异常和回滚。这样业务代码看起来清爽事务也不会因为漏了Commit而把连接池堵死。7.3 一点补充日志与监控最后再补充一个日常容易被忽略的视角。SqlSugar支持开启SQL日志把每个查询语句、参数值、执行时间打到日志里。调试问题的时候先开这个日志大部分问题从SQL语句层面就能定位到原因——是条件参数没拼对还是实体映射的列名不对还是N1查询导致频繁访问数据库。db.Aop.OnLogExecuting (sql, pars) { Console.WriteLine(sql); // 这里可以把日志接进你自己的日志框架 };这个AOP功能实际排查问题时非常有用。我见过很多次同事说我明明传了userId查询结果怎么不对打开SQL日志一看参数值为空或者类型转换错了一眼就发现问题。把日志等级调整好生产环境记录慢SQL开发环境输出完整SQL加参数整个数据层的可观测性会高很多。我是从上位机开发半路转过来的刚用SqlSugar那段时间面对一堆配置和特性确实有过反复查文档的经历。但用习惯之后我对这套技术栈的定位更清晰了SqlSugar MySQL不是万金油但在中小型业务系统、数据采集和内部管理平台上它把C#生态的工程化优势和MySQL的轻量部署结合得很好。只要你把连接串、批量写入、时间字段、事务、实体映射这五个基本功打扎实后面的开发基本就是一路顺风。希望这篇避坑指南能让你少走一些我走过的弯路。
