哥本哈士奇aspnetx这个ID跟着我在技术群里混了好些年。很多人乍一看以为是个都市名的谐音再看一眼才反应过来是只撒欢的狗就会心一笑。ID一半是在自嘲——我确实像哈士奇看到新技术就上头撒手就没影另一半是认真的——aspnetxASP.NET乘一个未知的x意思是我喜欢把框架里那些文档没写透的地方一点一点拆开来看。这篇内容就是我这些年做ASP.NET Core项目攒下的实战经验切片从项目结构、依赖注入、中间件到一次真实的线上事故复盘和部署上线的完整经历。如果你是刚入门的.NET开发者可以把它当成一份避坑地图如果你已经带过几个上了规模的项目也许能在里面找到几个平时没太在意的细节。先说清楚这篇不打算讲什么不讲基础语法不讲框架功能清单也不复读官方文档。我写的是那些“文档里不会写、但你真的会遇到”的问题以及我踩过之后怎么爬出来的过程。每个问题我都尽量说清楚背后的原理而不只是给一段能跑的代码。项目里那些看起来不起眼的决策——比如目录怎么切、依赖怎么注册、中间件怎么排、连接池怎么配——恰恰决定了系统上线之后是稳还是炸。1. 先聊聊“哥本哈士奇”这个ID以及它怎么变成了我的技术符号1.1 从老ASP.NET到ASP.NET Core一次并不轻松的转身我最早接触.NET是老ASP.NET Web Forms那一代页面生命周期、ViewState、服务端控件那套东西在当时确实让开发变得“像拖控件一样简单”。但项目一大就很痛苦页面和逻辑纠缠在一起测试基本靠手动点性能一上来就抓瞎。后来MVC出现才终于把关注点分离开但也仅仅是“分得更清楚”离好维护还有相当距离。真正让我下定决心转到ASP.NET Core的是几个硬指标跨平台部署、高性能、内置依赖注入、统一的中间件管道。当时抱着哈士奇式的好奇心开始试水结果第一版程序就栽了跟头——在Windows上好好的放到Linux服务器上直接502后来才发现是没有配置反向代理、也没监听对端口。这种“看着文档都懂、一上线就废”的体验我经历过太多次。但也正是这些跟头逼着我养成了追根究底的习惯。1.2 这篇经验串适合哪些人读完能拿到什么我把这篇定位成“实战经验切片”不是新手教程但新手也能从中受益。你已经会写基本的Controller和Service但项目一膨胀就觉得维护困难那第2章的功能切片思路会给你很大启发。你用依赖注入只是“接口配实现”就完事没想过作用域和生命周期的问题那第3章就是为你准备的。你在项目里被线上事故折腾过但还没沉淀出排查方法第5章的复盘链路值得反复看。所以这篇适用的场景大概是你在做ASP.NET Core项目或者即将接手一个已上规模的系统。你不满足于“能跑”你想知道为什么有些系统跑着跑着就出诡异问题想知道怎么在架构层面避免这些坑。读完以后我希望你能带走几样东西一套更抗改动的项目结构思路几个依赖注入的雷区名单一条中间件编排顺序的判断逻辑以及一份连接池事故的完整排查清单。这些都是我拿时间和线上的代价换来的性价比很高。2. 项目结构那关三层架构换成功切片维护成本真的降了2.1 三层架构的问题到底出在哪我刚带一个项目时用的是标准的三层架构Controller层、Service层、Repository层每层几十个文件目录看起来非常规整。但做了几个迭代之后别扭的感觉就来了。改一个订单功能我至少要打开Controller、Service、Repository、Entity四个文件很多时候还得在十几个长得差不多的Service里找到底哪个是订单的。最离谱的是跨模块的共享代码绕来绕去一个订单模块的修改可能要牵动权限、日志、通知三个模块回归测试范围越滚越大。现在回头看问题不在“分层”本身而在于这种切法是把代码按技术层级切没有按业务变化切。三层架构面对十几个模块时所有横向文件堆在同一层里你根本不知道哪个Repository属于哪个业务只能靠命名猜。当初微软那套分层模板是为“一个数据库对应一套CRUD”设计的业务稍微复杂就开始变形。项目的维护成本其实在一开始的结构决策里就注定了。2.2 功能切片到底是什么它和三层架构的本质区别所谓功能切片也叫垂直切片核心就一句话一个功能一个目录。把Controller、消息请求、处理逻辑、校验器、数据访问全部放在同一个文件夹下让这个功能相关的所有代码在同一个可见范围内。我重构过一个中型的后台系统结构长这样src/App/ Features/ Orders/ CreateOrder/ CreateOrderRequest.cs CreateOrderHandler.cs CreateOrderValidator.cs OrderCreatedEvent.cs GetOrders/ GetOrdersQuery.cs GetOrdersHandler.cs Shared/ OrderStatus.cs OrderNumberGenerator.cs Products/ ... Customers/ ...和三层架构对比一下就很明显三层架构里找代码是“按角色找”功能切片是“按业务找”。前者适合早期框架自动生成代码的阶段后者真正适合业务逻辑密集、变更频繁的中后期。比如订单的创建逻辑里校验、落库、发事件这三件事在切片结构里都待在同一个目录改起来只需要看一处在三层架构里校验可能在Service里落库在Repository里发事件又被扔到某个事件总线里搜索成本极高。2.3 我把一个老项目切成功能片段的实操步骤第一步识别业务功能边界。这个不需要什么高级分析直接看路由就行/orders、/products、/customers这些就是天然的边界。如果路由特别粗粒度那就先拆路由再拆代码。第二步建一个Features目录把Controller以及跟它相关的Service、Repository按功能搬进去。这一步机械但容易出错因为有些Repository被多个Controller共用搬的时候会牵一发动全身。第三步把真正跨功能共享的代码抽到Features/Shared里或者单独提到一个独立的基础设施项目。这里要注意一个度不是所有代码都需要共享比如订单模块内部用到的专用枚举、专用异常就应该留在订单目录里不要因为“以后可能复用”就提前抽出去。第四步把那些只服务一个功能的“万能Service”直接拆成数据处理类或命令处理器。如果某个Service里面只有两个方法而且只被一个Controller调用那它就没有继续存在的必要。我在重构时还引入了一个轻量级的命令/查询模式没有上重型框架就是简单的接口加处理器注册。收益是每个功能的入口非常清晰测试可以直接构造请求体调用处理器不需要启动整个Web服务器。缺点是文件数量会变多每个文件却都很小。有人看着多了几十个类会觉得“变复杂了”实际上恰恰相反——每个类的责任边界更清楚了。2.4 哪些项目不建议上来就切片功能切片不是银弹。如果项目是个极简API总共三五个接口两层结构就够了硬切反而增加认知负担。如果团队全是新人还没建立起领域概念切片会让他们“不知道文件该放哪”。我的判断标准很简单项目里是不是已经出现了一半以上的功能都要改同一层文件的现象如果是切片收益很大如果不是保持简单的分层挺好。顺便说一个我在重构时总结的经验改变结构最怕的是“边改边加需求”。我是在一个功能迭代相对空档的窗口期做的这次重构先用一到两周把结构和测试理清楚再开始加新功能。如果业务一直高速迭代的同时强行重组结构很容易改出新的问题最后都不知道是哪个变更引入的回归。3. 依赖注入构造函数爆炸、作用域泄漏还有随手new出来的那个雷3.1 内置DI用起来顺手但三大坑一个比一个阴ASP.NET Core内置了依赖注入容器几乎每个项目都在用。但正因为“拿来就能用”很多人会忽略生命周期和作用域问题。我在代码评审里见过大量“能跑但一上线就出诡异问题”的写法最常见的有三类。第一类是构造函数爆炸。一个服务类的构造函数里塞七八个参数满眼都是抽象接口看起来解耦很彻底实际是把复杂度从方法体挪到了组装现场。出现这种代码基本可以断定这个服务兼职太多它既在写业务、又在发通知、还在访问数据库。我的做法很简单把大服务按职责拆成几个小服务每个小服务只干一件事。接口数量不值得炫耀那是坏味道的信号。第二类是单例依赖了Scoped服务这种情况最阴险。典型场景一个后台任务服务注册成了Singleton为了访问数据库往里头注入IServiceScopeFactory然后手动CreateScope拿DbContext但忘了释放Scope。后果就是DbContext的生命周期被拉长成“整个进程级”数据库连接借了不还高峰期连接池迅速被耗尽数据读写还会出现串号的诡异问题。B用户在自己的请求里可能读到了A用户留下的未提交数据这种错在测试环境极难复现。// 错误示范Singleton服务里手动创建Scope但没释放 public class SyncService : ISyncService { private readonly IServiceScopeFactory _scopeFactory; public SyncService(IServiceScopeFactory scopeFactory) { _scopeFactory scopeFactory; } public void RunSync() { var scope _scopeFactory.CreateScope(); var db scope.ServiceProvider.GetRequiredServiceAppDbContext(); // 没有释放 scopedb 的生命周期被拉长成了单例 } }正确写法是把Scope放进using块或者干脆每处理一个任务就新建一个作用域、处理完立刻释放。第三类是随手new。很多同事为了“省几行代码”直接在业务类里new出来一个Repository或者Service。问题在于这个被new出来的对象内部往往又依赖了注入好的DbContext或其它服务等于绕过了容器把依赖链重新拉回手动装配状态。单元测试的时候又没法替换Mock对象每次测试都得连真的数据库。这种代码的修复不复杂把new出的对象改成构造函数注入就行但找出来需要一点耐心。3.2 怎么快速发现依赖注入环境里的问题我整理了一个检查清单每次接手项目都会照着过一遍检查所有注册成Singleton的服务看它们有没有直接依赖Scoped服务。如果有要么改成作用域工厂手动建Scope且用完即释放要么重新设计任务拆分别让单例长期持有一个随请求变化的对象。全局搜索代码里的“new”关键字看看new出来的对象是不是业务服务类如果是再看它内部有没有依赖容器管理的服务。有则必然是隐患。检查异步后台任务里是否有ServiceProvider的引用长期存在。一旦存在基本可以断定会造成作用域泄漏。这个清单不复杂但能拦下绝大多数依赖注入相关的线上事故。我在多个项目里都靠它提前排掉了雷。3.3 一个我验证过的检查习惯启动时把注册表打印出来依赖注入的坑之所以难发现是因为代码在编译期看起来完全正常。要更早地发现生命周期不一致的问题我有一个很土但有效的办法在服务启动时临时加一段代码遍历容器里已经注册的所有ServiceDescriptor把ServiceType、ImplementationType和Lifetime打印到启动日志里人工扫一遍。Singleton依赖Transient通常没问题但Singleton依赖Scoped就要引起警觉。foreach (var descriptor in services) { logger.LogInformation( {Service} - {Impl} [{Lifetime}], descriptor.ServiceType.Name, descriptor.ImplementationType?.Name, descriptor.Lifetime); }这个办法不需要装额外的诊断工具准备上线前跑一次基本能看清整个容器装配的真实情况。依赖注入不是目的目的是把对象的创建和装配交给容器让业务代码只表达“我需要什么”。只要记住生命周期一致性这条红线很多问题都能提前规避而不是等到线上暴雷才回头查。4. 中间件管道的正确顺序日志、异常、鉴权先谁后谁真的会影响事故4.1 中间件就像俄罗斯套娃顺序就是执行顺序ASP.NET Core的请求处理模型核心是中间件管道。它的运作方式像一个俄罗斯套娃每个中间件都决定“自己处理完要不要把请求传给下一个”。因此中间件的注册顺序严格决定了每个请求的执行顺序。这个“顺序即执行顺序”的特性很容易被人忽略一忽略线上就会出现各种玄学。我最开始写中间件时把异常处理放得特别靠后结果一个深层服务抛出来的异常直接绕过统一异常处理用户看到的是默认的500错误页日志里还只有半截访问记录。把异常处理挪到管道最前面之后所有未捕获异常都会在入口被拦截后面的日志和响应才有意义。这个调整没有改任何业务代码只是把注册顺序换了一下线上错误提示立刻变得友好了。这里给出我实际项目里验证过的推荐编排顺序UseExceptionHandler或者UseDeveloperExceptionPage放在最前面。UseHttpsRedirection把HTTP请求重定向到HTTPS。UseStaticFiles静态文件直接返回不进业务管道。UseRouting加载路由定义。UseCors跨域策略注册。UseAuthentication认证。UseAuthorization授权。自定义业务中间件比如日志、追踪ID、租户识别。UseEndpoints或者MapControllers终结点执行。这个顺序背后的逻辑可以概括成一句话异常处理要最早因为出现异常时你要确保响应能正常产生静态文件要在路由之前因为静态资源根本不需要走业务逻辑鉴权必须放在路由之后、终结点之前因为只有到了具体的端点你才知道该按什么策略去判断权限。4.2 一个高频中间件场景给每个请求发一张“追踪ID”自定义中间件里我使用频率最高、也最推荐每个人都做一个的是“追踪ID中间件”。作用很简单请求进来时生成一个Guid放进HttpContext.Items之后的每一步日志都带上这个ID。一旦用户反馈“我那条数据怎么没了”通过时间范围和用户ID我就能把整条链路的日志串起来。它的注册位次很有讲究。若放在路由之前所有后续中间件都能拿到同一个追踪ID若放在路由之后、终结点之前那路由匹配产生的日志就追踪不到了。项目里日志链路不完整很多时候就是中间件放的位置不对。一个简化的实现大致长这样public class TraceIdMiddleware { private readonly RequestDelegate _next; public TraceIdMiddleware(RequestDelegate next) _next next; public async Task InvokeAsync(HttpContext context) { var traceId Guid.NewGuid().ToString(N); context.Items[TraceId] traceId; context.Response.Headers[X-Trace-Id] traceId; await _next(context); } }这个中间件放在异常处理之后、路由之前再配合结构化日志把TraceId打进去排查问题的时候效率会提高一个档次。4.3 Use、Run、Map别搞混自定义中间件一多一个高频错误就会出现在中间件里忘掉调用_下一环节。我踩过一次在一个租户识别中间件里少写了一个await next()结果所有页面返回空白排查了很久才发现是请求被中间件截断了。Use是“处理完传给下一个”Run是“这里是终点不再传”Map是按路径条件分流。大多数业务中间件用Use就够了。还有自定义中间件的注册顺序和代码本身的先后编译顺序无关只跟你把它添加到管道的先后有关。这个认知理不清日志会出现明明中间件写在前面但没有先执行的情况——当然这是我看错了代码的位置它注册的是另一个管道分支。最后提一句CORS和鉴权的关系很容易被搞反。CORS是在服务端决定“允不允许浏览器跨域读取我的响应”鉴权是“这个用户有没有资格访问我的资源”两者是不同维度的两件事。如果CORS被放到鉴权之后某些预检请求就无法正确返回前端明明配了跨域却总是报错。这种问题不会让服务崩溃但会让前端同事暴躁到想打人。5. 那次连接池耗尽一次线上事故复盘我的数据库访问配置错在哪5.1 完整排查链路高峰期数据库不忙连接却没了我负责的一个内部后台系统某天高峰期突然大面积接口超时。性能指标一打开数据库的CPU和内存都不高但活跃连接数已经逼近数据库上限错误日志里开始刷“连接池已满请求超时”。当时我第一反应是“数据库扛不住了”但指标显示不是。接着怀疑是某条SQL锁表翻了慢查询日志也没有特别夸张的语句。再看应用侧发现有一个后台任务服务每秒轮询一次队列一旦队列里有任务就创建新Scope去处理。问题出在创建的Scope没有用using包住任务处理完Scope和里面的DbContext并没有立即释放。每轮轮询都new一个Scope仿佛会释放实际都被进程“挂”着连接池里的连接就这么被一点一点借光且永不归还。修复方案说出来很普通把Scope的创建和释放包进using块或者改成任务级的事务边界处理完立刻释放。改完之后连接数立刻回落到正常水位。但真正有价值的不是修复本身而是这个事故揭示的一个核心认知DbContext本身是轻量对象创建成本低但它的数据库连接是从连接池借来的用完必须还。任何让DbContext活过业务请求的写法本质上都是“借了不还”。5.2 连接池配置的正确姿势Max Pool Size不是越大越好排查过程中我顺手检查了连接字符串发现团队用的是默认配置什么都没显式设置。默认的最大连接数对单个服务足够但多实例部署时要重新算。我一般会在连接串里显式写清楚这些参数Serverlocalhost;DatabaseApp;User Idsa;Passwordxxx;Max Pool Size200;Min Pool Size5;Connection Timeout30Max Pool Size不是越大越好它和数据库端最大连接数、并发事务数量、锁竞争都有关系。我设置时会先算一笔账每个实例预期的并发请求数乘以实例总数再留20%左右的冗余这是最高连接数的一个合理起点。比如三个实例单个实例并发峰值稳定在50左右那Max Pool Size设200就够设800反而可能把数据库压垮。连接池耗尽这类事故根子通常不在参数而在代码的生命周期设计。参数只是最后一道防线。5.3 从这次事故里沉淀出的检查习惯这次事故之后我给自己定了几条铁律代码评审时凡是看到IServiceScopeFactory都停下来问一声这个Scope多久释放不释放就不许合代码。依赖数据库的服务从不在构造函数里直接拿DbContext实例而是通过注入作用域拿。线上增加连接池和活跃连接数的监控指标超过阈值就告警而不是等用户报障。每次修完线上事故把根因、现象、解决步骤写进团队的排障手册而不是只改代码。其中最后一条看起来最“虚”但长期价值最大。事故排障很多时候是“痛苦的重复”和“高级的重复”之间的差别。写手册的人未必记得所有细节但下次同类问题出现时排查时间可能从半天缩到半小时。6. 部署上线从裸跑Kestrel到容器化中间那几次翻车6.1 裸跑Kestrel的岁月systemd托管与那几个低级错误项目早期我在服务器上直接运行发布产物再用systemd托管进程。这套方案本身没问题但很容易栽在细节上。最经典的是忘记设置ASPNETCORE_URLS默认只监听localhost外网访问直接拒绝再就是静态文件权限不对图片加载不出来最离谱的是有人把环境变量设成了Development线上跑着开发配置连接串都指向本地数据库。那段时期每回上线都像开盲盒本地好好的线上各种报错。后来我强制规定所有配置必须通过环境变量覆盖开发环境的数据不要硬编码进配置仓库线上连接串一律从部署平台的环境变量里读取。这套规则立下来环境差异导致的低级错误终于消停了。6.2 容器化的第一版多阶段构建与最小镜像再往后我把部署切到了容器化。多阶段构建的Dockerfile是基础配置FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build WORKDIR /src COPY . . RUN dotnet publish -c Release -o /app/publish FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS runtime WORKDIR /app COPY --frombuild /app/publish . ENV ASPNETCORE_ENVIRONMENTProduction EXPOSE 8080 ENTRYPOINT [dotnet, App.dll]第一版容器化也踩了不少坑最典型的是镜像构建完一启动容器显示“运行中”但应用其实在崩溃重启。原因是没加健康检查编排工具只看到进程还在就认为服务正常。后来我在镜像里加了一个健康检查接口并配合编排工具的探针来确认“服务的就绪”状态。镜像小不小、层多不多这些都是优化项健康检查才是保命项。如果只是单服务部署docker-compose已经够用。下面是一个经过验证的简化配置services: app: build: . ports: - 8080:8080 environment: - ASPNETCORE_ENVIRONMENTProduction - ConnectionStrings__AppServerdb;DatabaseApp;User Idsa;Password${DB_PASSWORD};Max Pool Size200 depends_on: - db db: image: postgres:16 environment: POSTGRES_PASSWORD: ${DB_PASSWORD}6.3 容器化之后的新坑数据保护密钥、环境一致性和服务编排容器化之后环境一致性大幅提升但有些问题反而被放大了。一个特别容易被忽略的是数据保护密钥。ASP.NET Core的Cookie、防伪标记、部分缓存加密都依赖数据保护API。默认情况下密钥存在本地文件系统里多实例部署时每个实例会生成各自的密钥用户登录状态就会出现“这台机器有效、换一台就掉线”的诡异现象。解决方向是显式配置数据保护密钥的存储位置让所有实例共享同一个密钥仓库比如持久化到网络存储或数据库。这个问题在单机时代几乎不会遇到容器化一上多副本马上就暴露出来。对于刚从裸跑切换到容器的团队我的建议是别急着上规模很大的编排系统先用Compose把单服务跑稳把镜像构建、配置注入、健康检查、日志收集这几件事做扎实再考虑扩展。上层的复杂度是下层简单性堆出来的。基础设施不稳时编排只会让事故范围更大而不会让系统更可靠。最后说一个我个人坚持了很久的小习惯每次修完一个线上事故都会把根因、现象和解法写进团队的排障手册。代码会改记忆会淡手册不会骗人。这大概是“aspnetx”这两个字母对我最真实的意义——x不是交叉路口是不确定。而一个开发者的成长路径往往就是由一个个“处理好的不确定”拼出来的。项目结构按业务功能切依赖注入时刻检查生命周期中间件顺序想清楚再排数据库连接用完必须放部署前先处理好配置和密钥。这几条看起来都不难但我每一次线上翻车几乎都能追到其中一条。希望这篇“哈士奇式”的经验积累能帮你少拆几次家。