1. 为什么一个“能跑起来的骨架”比十篇架构文章更有用1.1 从“我要不要自己搭分层”这个纠结说起每次有新项目立项最先卡住的往往不是业务需求而是那句“基础框架怎么搞”。我自己经历过至少三次从零搭 Clean Architecture 的过程第一次兴致勃勃画了一堆分层图结果真正写业务的时候发现引用关系全乱了第二次学乖了把依赖方向卡死但基础设施层的日志、缓存、认证又全是手写写到第四个接口就开始复制粘贴第三次决定抄一个现成的挑了半天要么太薄薄得只剩一个空 Web API 项目要么太厚厚到里面塞了几十个用不上的组件。.NET 8 作为长期支持版本发布之后社区里这类“起始模板”一下子多了起来。FullStackHero .NET 8 Starter Kit就是其中比较典型的一个它不是一个库也不是一个框架而是一套已经做完大量基础工程决策的项目骨架你拉下来改改就能当自己项目的起点。它把分层、模块化、多租户、认证授权、缓存、后台任务、API 文档这些“每个项目都要做一遍但又没什么新意”的活儿提前做掉了。我用它搭过两个内部管理系统也在一个对外服务的小项目上试过它的多租户能力。这篇不是官方文档的翻译而是我把这套骨架拆开、跑通、改造完之后的一些记录。如果你正在评估“下一个 .NET 8 项目要不要用它起步”或者你已经在用但被某个配置卡住了下面这些内容应该能省你不少时间。1.2 这个模板到底把哪些决策做完了评估一个起始模板别只看它引用了多少包要看它替你做了哪些不可逆或成本很高的决策。我把这套骨架里已经定好的关键选择列了一下你可以对照自己项目的实际情况判断合不合拍决策项模板给出的答案这个选择的代价架构风格模块化单体Modular Monolith后期拆微服务有改造量但比一开始就拆省太多事分层方式每个模块内部分 Domain/Application/Infrastructure文件数量翻倍小项目会显得重请求处理CQRS MediatR简单 CRUD 也要写 Handler有学习曲线接口组织端点模块化Carter 风格与传统 Controller 写法不同数据访问EF Core PostgreSQL 优先换库要动迁移和部分 SQL多租户内置租户解析与隔离单租户项目会觉得是负担认证授权JWT 细粒度权限策略需要理解权限字符串的匹配规则后台任务Hangfire 独立面板需要额外的存储支持这份表里最值得注意的不是“它选了什么”而是“这些选择彼此咬合得很紧”。比如你选了 CQRS MediatR那么端点层就天然适合做成极薄的模块只负责把请求丢给 MediatR再比如有了多租户EF Core 的 DbContext 就必然要被租户上下文接管。这种一致性是手搭框架最难保证的部分——手搭到第三个模块的时候往往会发现第一个模块的写法已经和现在不一样了。1.3 适合谁、不适合谁说句实话这套骨架不是万能药。我见过有同学拿它做一个只有五张表的内部工具结果光理解目录结构就花了两天最后抱怨“太重”。也见过有人直接把它当微服务模板用起手就想拆最后卡在跨模块事务上。我的判断标准比较粗糙但好用如果你预期这个项目在一年内会出现三个以上的独立业务域并且至少有一个域需要按客户隔离数据那它值得用如果你只是要一个星期内交付一个 CRUD 后台用它反而拖慢你。还有一类人特别适合正在从传统三层架构往模块化方向迁移的团队。这套骨架提供了一个现成的“中间态”——它还没到微服务的复杂度但已经把模块边界、依赖方向、横切能力这些该有的约束立起来了。团队照着它的目录结构写半年很多架构上的坏习惯会自然被纠正。2. 从零到第一个 200 响应模板安装与环境拉起的完整链路2.1 前置环境清单与版本对齐先泼一盆冷水这套骨架跑不起来的情况里一大半是版本没对齐。它依赖的东西比一个纯 Web API 项目多任何一环版本错位都可能表现成“莫名其妙启动失败”。我建议按下面这份清单逐项核对别跳.NET SDK 8.0.x用dotnet --list-sdks确认如果机器上装了 6/7/8 多版本注意global.json的存在会改变默认 SDK。PostgreSQL 15 或 16模板默认用它。容器里起最省事本地装也行但要注意端口别和已有实例冲突。Redis缓存和部分会话能力依赖它。没有它某些功能会降级但服务通常能起来——这点很重要后面章节会细说。Docker可选但强烈建议不是为了部署是为了让数据库、缓存、日志面板这些周边依赖一键起来避免在环境上耗费半天。一个能看日志的终端听着像废话但这套骨架启动时会打大量信息用 IDE 的输出窗口经常滚没了我后来一律用命令行dotnet run观察首启。提示如果你机器上同时装了多个 SDK 版本进入项目目录后先跑一次dotnet --version确认输出的确实是 8.x。我曾经因为一个残留的global.json导致构建报了一堆莫名其妙的语法错误排查了半小时才发现 SDK 用的是 7。环境这块还有个小细节模板的后台任务面板、日志收集这些组件往往会额外占端口。第一次启动前用netstat或者系统自带的端口查看工具扫一眼把常用的几个端口五千、五千零一这类留出来别到时候一个个改配置。2.2 模板安装与项目生成这套骨架提供两种用法直接克隆仓库改或者以dotnet new模板的方式安装后生成新项目。我更推荐后者因为克隆仓库会带着它的 Git 历史和一堆示例提交记录清理起来烦。模板方式生成的项目是干净的命名空间也按你给的项目名替换好了。大致的操作链路是这样# 先确认模板源具体包名与版本以仓库 README 当前说明为准 dotnet new install FullStackHero.NETStarterKit # 查看可用的模板短名 dotnet new list # 生成项目-n 指定解决方案名 dotnet new fsh-api -n MyCompany.Portal -o ./MyCompany.Portal生成完之后先别急着dotnet run做两件事。第一件是看一眼解决方案里的项目数量如果比你预期的多很多说明模板把可选模块也带上了可以按需删第二件是打开根目录的配置文件把连接字符串改成你自己的。我见过有同学跳过模板安装直接git clone之后在 IDE 里生成解决方案结果因为路径里有空格或者中文构建直接失败。路径里不要有空格和中文这条老规矩在带 Docker 编排的项目里尤其重要因为容器挂载路径会跟着出问题。2.3 依赖容器与连接字符串的第一次对齐生成项目之后第一道真正的门槛是让服务和数据库对上话。模板一般会自带一份docker-compose文件里面定义了数据库、缓存、日志收集这几个服务。我的习惯是先起来再改配置而不是先改配置再起来——因为默认配置本身就是自洽的先用它验证“整条链路是通的”再逐步换成自己的值出问题时更容易定位是哪一步改坏的。# 在项目根目录或编排文件所在目录执行 docker compose up -d # 看容器状态确认数据库和缓存都是 healthy docker compose ps起来之后配置里的连接字符串要和容器暴露的端口、账号严格对应。这里有一个高频错位编排文件把数据库端口映射到宿主机的一个非默认端口比如五千四百三十二但你配置文件里写的是默认的五千四百三十二反过来——总之端口、库名、用户名、密码这四项里错一项表现都是启动时抛出连接异常。{ DatabaseOptions: { ConnectionString: Hostlocalhost;Port5432;Databaseportal_db;Usernamepostgres;Passwordyour_password }, CachingOptions: { RedisURL: localhost:6379 } }密码这种敏感值不要写在配置文件里提交到仓库。模板通常支持环境变量覆盖本地开发用用户机密dotnet user-secrets或者.env文件别图省事直接明文写进appsettings.json这习惯一旦养成早晚会出事。2.4 首次启动会发生的三件事第一次dotnet run启动主 API 项目日志会刷得很快。别慌你只需要盯三件事第一数据库迁移有没有自动执行。很多这类骨架在开发环境启动时会自动把待应用的迁移跑一遍日志里会出现类似“Applying migration”的字样。如果迁移失败服务通常会直接退出这时候往上翻日志找第一个异常别从最后一行往前猜。第二种子数据有没有灌进去。首次启动一般会创建默认租户、默认管理员账号、基础权限列表。这些种子数据是后面登录和调接口的前提如果没灌成功你会在登录时遇到“用户不存在”这种让人怀疑人生的错误。第三监听地址和端口。控制台会打印Now listening on: http://localhost:xxxx把这个地址记下来后面调接口全用它。三件事都正常的话打开浏览器访问 API 文档页面应该能看到分组好的端点列表。这时候别急着测业务接口先测一个不需要认证的端点比如健康检查或者版本信息确认整条管道是通的。很多“调不通”的问题其实出在反向代理、端口占用或者 HTTPS 重定向上先从最简单的端点验证能省掉大量猜测。3. 目录结构拆解Hosts、Modules、BuildingBlocks 各自的真实职责3.1 Hosts 层只做组装不做业务打开解决方案最外层通常是Hosts或者类似名字的目录里面放着真正 executable 的项目也就是你dotnet run的那个。这一层的定位非常明确它是一个装配车间不是生产车间。装配车间都干些什么注册服务、配置中间件管道顺序、挂载各模块的端点、读取配置、初始化日志。仅此而已。你在这一层里不应该看到任何业务判断比如“如果用户是管理员就怎样怎样”——这种逻辑一旦出现在 Hosts 层就说明模块边界已经开始漏了。中间件顺序是这一层最容易被搞错的地方。管道是有严格先后顺序的认证必须在授权之前异常处理必须尽可能靠前跨域处理的位置会影响预检请求能不能通过。我见过一个典型问题跨域中间件放在了认证后面结果前端带 Token 的预检请求被拦下来浏览器控制台报的是跨域错误实际根因是管道顺序。// 顺序只是示意重点是理解每一段为什么在这个位置 app.UseExceptionHandling(); // 最靠前保证后面任何环节抛异常都能被兜住 app.UseCorrelationId(); // 给每个请求打上追踪标识 app.UseAuthentication(); // 先认人 app.UseAuthorization(); // 再判权 app.UseMultiTenancy(); // 租户解析要早于业务处理 app.MapModules(); // 最后才是端点映射3.2 Modules 层一个模块内部分成哪几层Modules目录下每个子目录就是一个业务域比如身份、租户、业务主数据之类。每个模块内部又会分成三层领域层放实体和领域规则应用层放命令、查询、处理器和校验基础设施层放数据库上下文、仓储实现、外部服务调用。这层的价值在于边界是物理隔离的。因为每个层是独立项目独立程序集你在应用层想直接引用另一个模块的基础设施层编译期就会报错。这种“用编译器强制约束架构”的做法比写在文档里的约定靠谱一万倍。模块内部我一般按功能而不是按技术类型组织文件Modules/Identity/ Identity.Domain/ 实体、值对象、领域异常 Identity.Application/ 命令、查询、Handler、Validator Identity.Infrastructure/ DbContext、迁移、仓储实现、外部适配按功能组织的好处是当你需要删掉一个业务域时直接删一个目录就行按技术类型组织把所有 Handler 放一个目录、所有实体放一个目录则会出现“删了一半留了一半”的尴尬。还需要注意一点模块之间如果要通信只允许通过应用层暴露的接口或者事件总线不允许直接引用对方的 DbContext。跨模块共享数据库表是模块化单体退化成“大泥球”的最快路径我在这上面栽过后面章节会具体讲。3.3 BuildingBlocks 层横切能力为什么要独立BuildingBlocks是这套骨架里我最认可的设计。它把所有“不止一个模块要用、但又和具体业务无关”的东西抽了出来核心抽象、持久化基类、Web 层的过滤器与中间件、缓存封装、事件总线、邮件、存储、后台任务。为什么要独立因为这些东西的生命周期和业务模块完全不同。业务模块会随需求变化频繁改动而横切能力相对稳定把它们混在一起你会遇到“改一个缓存封装导致所有业务模块重新编译”的情况编译时间在项目大了之后是实打实的成本。更实际的原因是替换成本。举个具体例子模板默认用某个缓存客户端访问 Redis如果哪天你需要换成内存缓存或者别的实现只要BuildingBlocks.Caching暴露的接口不变业务模块一行都不用改。这就是把变化点关起来的意义。这里我要提个反过来的坑BuildingBlocks不是垃圾桶。我曾见过有人把所有“暂时不知道放哪”的代码都扔进去半年后这个目录变成了第二个业务层。判断标准很简单——如果一个类只被某一个模块使用它就不属于 BuildingBlocks。3.4 依赖方向与“谁能引用谁”这套骨架最核心的隐性规则是依赖方向。把它记成一句话外层依赖内层内层不知道外层存在。领域层不引用任何东西应用层引用领域层基础设施层引用应用层Hosts 层引用所有模块的基础设施层用来注册服务。违反这条规则的典型症状是领域实体上出现了[Required]或者[Column]这类持久化特性。一旦实体被 EF Core 的特性污染你就再也无法在纯内存场景下使用它了单元测试也变得难写。模板默认会用 Fluent API 而不是特性来配置映射这个细节值得保留。模块之间的依赖也要卡死。如果 A 模块确实需要 B 模块的数据正确做法是 A 依赖 B 的应用层接口而不是基础设施层或者用事件做异步解耦。我在项目里定过一条土规矩模块项目文件里的ProjectReference只能指向 BuildingBlocks 和自己的分层指向别的模块一律要在代码评审时说清楚理由。这条规矩挡住过好几次越界。4. 多租户这套骨架里最容易被低估的一块4.1 租户从哪里来解析策略与优先级多租户不是一个开关它是一条从请求进来到数据落库的完整链路。第一步是租户识别这次请求到底属于哪个租户常见策略有几种从请求头里读、从路径里读比如/api/{tenant}/...、从子域名里读、从 JWT 声明里读。这套骨架默认支持前两种的组合解析器按优先级依次尝试第一个命中的生效。优先级顺序很重要因为它决定了一个请求同时带了请求头和路径租户时以谁为准。// 思路示意解析器按顺序尝试命中即停 options.Strategies.Add(new ClaimStrategy(...)); // 登录后的用户声明最可靠 options.Strategies.Add(new HeaderStrategy(...)); // 服务间调用 options.Strategies.Add(new HostStrategy(...)); // 按子域名区分我的经验是登录后的请求优先用声明里的租户未登录的请求用请求头或路径。为什么因为声明是服务端签发并校验过的请求头是客户端随便传的。如果两种都允许且请求头优先那就会出现“用户 A 传了用户 B 的租户标识就能跨租户访问”的严重问题。这里有个容易被忽略的点租户不是登录信息。用户可以属于多个租户登录时选定一个之后所有请求都带着这个选择。如果你的业务里存在“一个账号管理多个客户”的场景这一点必须在设计初期就想清楚后补会很痛苦。4.2 数据隔离的三种粒度与选型识别出请求属于谁第二步是决定数据怎么隔开。三种粒度成本依次上升隔离方式实现方式适用场景主要代价共享表 租户列每张表加租户字段全局查询过滤器自动加条件租户多、数据量中等、要跨租户统计隔离性最弱漏加过滤器就串数据独立 Schema每个租户一组表同一个库租户数量可控、要一定隔离性迁移要跑多遍运维复杂度上升独立数据库每租户一个库强隔离要求、租户数量少成本最高备份和升级都要考虑模板默认走的是第一种配合全局查询过滤器。这个方案对绝大多数 SaaS 够用但它有一个致命前提所有查询路径都必须经过过滤器。原生查询、手写 SQL、缓存键、后台任务里拼的查询全都要单独处理。我踩过一次坑某个后台导出任务用的是原生 SQL完全绕过了 EF Core 的查询过滤器结果导出文件里混进了别的租户数据。事后复盘问题不在于方案选错而在于我们没有为“绕过过滤器”这件事建立强制检查。现在的做法是任何手写查询的地方方法签名上必须显式接收租户标识参数让编译器提醒你“这里需要租户上下文”。同时缓存键一律拼接租户标识否则会出现 A 租户的数据被缓存后返回给 B 租户——这个 bug 极其隐蔽因为本地单租户测试永远发现不了。4.3 调试多租户时最常见的三个症状多租户相关的 bug 有个特点表现和根因隔得很远。我总结了三个高频症状你遇到时可以直接往这几个方向查。第一个症状是**“数据时有时无”**。同一个接口有时候返回三条有时候返回零条。这多半是租户标识在某条路径上丢了比如某个中间件重置了请求上下文或者异步方法里await之后上下文没正确流转。查法是在 DbContext 里打一条日志把当前解析到的租户标识和最终 SQL 里的租户条件都输出出来一眼就能看出是哪个环节丢的。第二个症状是**“新租户创建后不生效”**。租户数据一般是存库的创建后需要刷新缓存如果有缓存或者等缓存过期。如果你用的是分布式缓存而创建租户的实例和读取租户的实例不是同一个就会看到“这个实例知道新租户、那个实例不知道”。解决办法通常是在租户变更时主动失效缓存或者在读不到时回源查库而不是直接当不存在。第三个症状是**“切换租户后还看到旧数据”**。这往往不是后端的问题而是客户端缓存或者服务端响应缓存没带租户维度。缓存键里漏了租户标识是这类问题的头号原因。5. 权限模型与 JWT从登录到 403 的完整链路5.1 用户、角色、权限的三层关系这套骨架的权限模型是三层用户、角色、权限。用户绑角色角色绑权限权限是字符串形式的细粒度标识比如类似“用户.查看”“用户.编辑”这种点分格式。授权的时候比对的是权限字符串不是角色名。这个设计和“只判断角色”相比好处很明显新增一个“只能看不能改”的角色不需要改任何代码只要在角色与权限的映射表里加一条就行。坏处是权限字符串会膨胀管理界面没做好就会变成几百个复选框。我的维护建议是权限粒度控制在“一个端点一个权限”别再往下拆到字段级。字段级的权限控制放在业务逻辑里判断不要塞进授权策略否则策略会变得难以理解、难以测试。还有一点值得注意权限变更后已经签发的 Token 里如果带着权限列表是不会自动更新的。要么强制重新登录要么在服务端做实时校验。模板的做法通常是在生成 Token 时把权限塞进声明换取的是每个请求少一次查库——这是性能与实时性的权衡你要清楚自己选了哪一边。5.2 自定义授权策略是怎么挂上去的标准的那套基于角色的授权不够用所以模板通常会自定义一个基于策略的授权扩展让端点上一行特性就能声明“这个接口需要什么权限”。// 端点声明处思路示意 app.MapGet(/users, handler) .RequirePermission(Permissions.Users.View);背后的机制是注册一个自定义的授权策略提供者它读取端点上的元数据拿到需要的权限字符串然后在授权处理器里和当前用户声明中的权限列表比对。理解了这条链路调试就有的放矢了——是策略没注册上还是处理器没被调用还是声明里压根没有权限三种情况表现完全不同。我遇到过一个特别隐蔽的问题某个端点加了权限特性但始终返回 200等于权限没生效。查了半天发现是端点注册顺序的问题——特性加在了分组上而实际处理请求的是另一个没加特性的子端点分组上的元数据没有继承下来。这类问题没法靠猜只能加日志把“当前端点的授权要求”打出来。5.3 401 和 403 分不清时怎么查这两个状态码太容易混。401 是“我不知道你是谁”403 是“我知道你是谁但你不能干这个”。实际排查时经常出现“明明带了 Token 却返回 401”这类问题的原因清单我列一下按出现频率从高到低现象常见原因快速验证带 Token 仍 401签名密钥不一致多实例配置不同换成单实例重试带 Token 仍 401签发方或受众校验失败解码 Token 比对配置项带 Token 仍 401时钟偏差超过允许窗口检查服务器时间同步登录成功但立即 403Token 里没有对应权限声明解码 Token 看声明列表部分接口 403权限字符串拼写或大小写不一致统一大小写策略刷新页面后 401客户端没带 Authorization 头看浏览器网络面板请求头时钟偏差这一条特别值得说。Token 里有过期时间服务端校验时会允许一个时间偏移窗口。如果签发和校验的两台机器时间差了十几分钟就会出现“刚签发的 Token 立刻被判无效”。容器环境里这个情况不罕见因为容器时间跟着宿主机走而宿主机的时间同步服务可能没开。还有个细节授权失败返回 401 还是 403取决于认证有没有成功。如果认证中间件没跑比如端点没标记需要认证那它可能连 401 都返回不了直接 200 或者 404。所以排查时先要确认这个端点到底有没有进入认证管道。6. EF Core 迁移与种子数据这套模板的正确打开方式6.1 为什么迁移必须指定启动项目这套骨架的数据库上下文不在启动项目里而是在各模块的基础设施层。这就导致一个很常见的卡点直接跑dotnet ef migrations add会失败报“找不到 DbContext”。原因很直白——EF Core 工具需要找到一个可执行的程序集来构建服务提供者并且需要知道从哪里读取配置。默认它瞄准当前目录的项目但当前目录是个类库类库里没有Program.cs也没有配置文件自然找不到 DbContext。正确姿势是两个参数一起给dotnet ef migrations add AddUserTable \ --project src/Modules/Identity/Identity.Infrastructure \ --startup-project src/Hosts/Api \ --context IdentityDbContext--project指定迁移文件输出到哪儿--startup-project指定配置和服务注册从哪儿来。有多个 DbContext 的时候必须加--context否则工具会报“多个上下文”的错。还有一个坑迁移生成的位置和你当前所在的目录有关。一定要在解决方案根目录执行别进到某个子目录再跑否则相对路径会算错报“找不到项目文件”。6.2 种子数据与首次初始化的顺序首次启动时通常有两件事要做应用迁移、灌种子数据。这两件事有严格顺序反了一定失败。更麻烦的是如果种子数据里包含外键关系比如角色权限映射需要角色和权限都存在那这几步之间也有顺序。我的做法是把初始化拆成一个独立的引导流程按固定顺序执行每一步失败都明确报错并终止检查数据库是否存在不存在则创建应用该模块的所有待处理迁移检查种子标记比如是否已有租户记录没有才执行灌入灌入完成后写一条初始化记录防止重复执行。第三步的“检查标记”很关键。如果不做幂等每次重启都会重新灌一遍轻则产生重复数据重则因为唯一约束直接启动失败。我见过有项目因为种子数据不幂等在容器编排里重启三次后起不来了排查起来还以为是数据库挂了。另一个细节是种子数据里别写敏感默认值。默认管理员账号的密码如果是硬编码的那这套代码一旦进了生产就是个大窟窿。做成从配置或环境变量读取首次启动强制要求提供没提供就报错退出——这个“失败优先”的设计比默默用默认值安全得多。6.3 并发启动下的迁移竞争开发环境单实例跑没问题一上多副本就出事多个实例同时启动同时检测到有待应用迁移同时执行建表结果互相冲突一部分实例启动失败。这种情况的典型日志特征是“relation already exists”或者锁等待超时。解决办法有几种成本和适用性不同部署阶段单独跑迁移把迁移做成一次性任务在所有实例启动前执行完。这是最干净的做法我现在的项目一律这么干。加分布式锁启动时先抢锁抢到的执行迁移没抢到的等待。实现起来要引入锁组件但能保证幂等。迁移和数据访问彻底分离服务启动时完全不碰结构变更只负责读写。对运维要求高但生产环境最安全。开发环境我一般保留自动迁移方便本地快速迭代配置里用一个开关控制生产环境关掉。这个开关一定要默认关闭而不是默认开启——默认开启的话某次部署忘了改配置就可能在生产库上跑迁移。7. 实测踩坑几个能让服务起不来的配置细节7.1 连接串与容器端口的错位前面提过端口错位这里展开说。容器编排里的端口映射是“宿主机端口:容器端口”而应用跑在宿主机上时用的是宿主机的端口跑在容器里时用的是容器端口。你的应用跑在哪儿决定了你连接串里写哪个端口。调试时本地跑应用、数据库在容器里 → 连接串写宿主机的映射端口应用也进了容器、和数据库在同一个编排网络里 → 连接串写容器名 容器端口。这两种情况混用是最常见的启动失败原因症状是连接超时不是连接被拒因为端口根本没在监听。快速验证方法宿主机上直接用数据库客户端连那个端口能连上说明映射没问题再进容器里连容器名能连上说明网络没问题。两头都通而应用连不上那就是应用读到的配置不是你以为的那份。配置文件加载顺序也值得说一句环境变量会覆盖配置文件开发环境的配置文件会覆盖基础配置文件。你改了appsettings.json没生效很可能是环境变量或者appsettings.Development.json里的同名键把它盖住了。排查时把最终生效的连接字符串脱敏后在启动日志里打出来比猜快一百倍。7.2 CORS 与前端本地调试前端本地跑在七千多端口后端跑在五千多跨域是必然的。这套骨架的跨域是在 Hosts 层配置的支持按来源名称或者正则匹配。最常见的错误是“来源写死了但前端端口变了”。前端的开发服务器端口有时候会自动往后顺延端口被占用时你配置里只允许某一个端口就会突然全挂。我的做法是开发环境用正则允许本机所有端口生产环境用精确列表。这个区分要在配置里明确做出来不能靠人工记得改。还有一个细节带认证信息的跨域请求不允许来源用通配符。如果你的前端需要携带 Cookie那配置里必须明确列出具体来源通配符会被浏览器直接拒绝。这个限制是浏览器的安全策略不是后端能绕过的。预检请求失败时控制台的报错信息往往很含糊。快速定位的方法是在浏览器网络面板里找那个方法为 OPTIONS 的请求看它返回的状态码和响应头。如果是 404说明后端没处理 OPTIONS 请求如果是 405说明方法没被允许如果有响应但缺了允许来源的头那就是配置没匹配上。7.3 缓存、任务面板这些“非核心”依赖挂了会怎样这套骨架把 Redis、后台任务、日志收集都做成了可插拔的。理论上缺了它们主流程还能跑但实际表现要看具体实现。缓存挂了通常不会导致启动失败但会导致每次请求都回源查库性能断崖式下跌。如果你的缓存封装里对异常做了吞掉处理那连报错都不会有只是慢——这种“静默降级”在压测时才会暴露很危险。我建议至少在启动时做一次缓存连通性探测连不上就在日志里打一条醒目的警告别让它悄悄降级。后台任务面板挂了会麻烦一些。后台任务通常需要一个持久化存储来记录任务状态如果存储不可用任务注册阶段就可能抛异常直接导致启动失败。所以这类组件最好做成“连不上就跳过注册”并在健康检查里暴露出来而不是让整个服务起不来。日志收集组件相对安全连不上顶多丢日志。但要注意日志框架的初始化时机——如果它在服务容器构建之前就尝试连接连不上可能会阻塞启动。这类问题的表现是“启动卡住不动”没有报错看着像死锁。遇到这种情况先把日志输出目标改成控制台能启动之后再排查远端连接。8. 把它改成自己的项目剪裁顺序与命名空间替换8.1 先删什么后改什么生成项目之后的第一件事不是加功能是减法。模板带的东西比你需要的多留着不用只会增加理解成本。我的剪裁顺序是这样的先删示例业务模块如果模板带了演示用的模块再删用不上的横切组件比如用不上对象存储就把那部分摘掉最后删端点。顺序不能反——先删端点再删模块会留一堆编译错误改起来很痛苦。删的时候有个技巧从解决方案文件里移除项目引用而不是直接删目录。直接删目录会让引用它的项目全部报错你得一个个去修。先从解决方案里移除再清理引用最后删文件错误会少很多。还有一类东西不要急着删健康检查、版本信息端点、异常处理中间件。这些看起来可有可无但在排查问题时价值极高。我一般保留它们改成需要认证才能访问而不是直接删掉。8.2 命名空间与项目名的批量替换风险把模板改成自己的项目绕不开批量替换命名空间。这件事看着简单实际上坑不少。第一个坑是替换顺序。如果你把旧前缀替换成新前缀但新前缀里包含旧前缀就会出现重复替换。比如旧的是App新的是App.Portal替换完全变成App.Portal.Portal。解决办法是先替换成中间标记再替换第二遍或者用带边界的正则。第二个坑是配置文件里的键名。有些配置节的名称是跟着项目名走的代码里替换了但配置文件没替换运行时会读不到配置。替换完一定要全局搜一遍旧前缀把json、yaml、csproj、sln全都覆盖到。第三个坑是数据库对象名。迁移文件里可能带着旧前缀的表名或者 Schema 名。如果项目还没上线直接删掉重新生成迁移最干净已经上线的话只能新写一个重命名迁移。8.3 后续演进模块化单体什么时候该拆最后聊一个必然会遇到的问题这套骨架是模块化单体什么时候该往微服务走我的判断标准是三个信号出现两个以上才值得考虑某个模块的扩容需求和别的模块明显不同比如报表模块要十倍资源其他模块不需要某个模块的发布节奏严重拖累其他模块改一行要全量回归团队规模大到模块边界变成了沟通瓶颈一个模块超过两个小组共管。反过来说如果只是觉得“微服务听起来先进”那千万别拆。我见过一个团队四个人的规模把一个好好的模块化单体拆成八个服务结果光是本地起全套环境就要十几分钟联调一个跨服务流程要开四个终端。后来他们又合回去了代价是两个月。模块化单体的好处是拆的时机由你掌握。因为模块边界已经清晰、通信已经走接口或事件真要拆的时候把某个模块的基础设施层换成远程调用就行业务代码基本不动。这才是这套骨架真正的价值——它不承诺让你永远不拆而是让你在需要拆的那天不用从零开始重构。我个人在实际操作中的体会是这套骨架最值得学的地方不是它的代码而是它的约束。代码你可以换目录你可以改但“依赖方向不能乱”“模块之间不许共享数据库”“横切能力要独立”这几条约束是它能长期演进的根本。我在自己的项目里把这几条写进了代码评审清单比任何架构文档都管用。