Crping.EFCore.Controller 8.8.0

Crping.EFCore.Controller

基于Crping.EFCore的WebApi的增、删、改、查、分页等常用方法实现！

版本更新说明

---

8.8.0

2026年8月11日 星期二

与 Crping.EFCore / Crping.EFCore.Common 同步升至 8.8.0

• 无功能性变更，仅同步版本号（Keyset 排序键点分路径 / bool 排序键修复 / OrderBy 全能化重构在 Core 层 DAL/BLL，Controller 透明）

---

8.7.0

2026年8月11日 星期二

与 Crping.EFCore / Crping.EFCore.Common 同步升至 8.7.0

破坏性变更 — 分页结果契约属性顺序调整与 required 强化

• KeysetPage<T> / OffsetPage<T> 的 PageInfo / Pagination 属性移至 Items 之前
• 两个属性均改为 required init（移除默认值），调用方构造时必须显式提供所有属性
• 迁移指南：JSON 反序列化顺序可能变化，手动构造对象时需调整属性顺序或使用命名参数

---

8.6.0

2026年8月10日 星期一

与 Crping.EFCore / Crping.EFCore.Common 同步升至 8.6.0

• 无功能性变更，仅同步版本号（OrderByExpr 任意表达式排序在 Core 层，Controller 透明）

---

8.5.0

2026年8月9日 星期日

与 Crping.EFCore / Crping.EFCore.Common 同步升至 8.5.0

新功能 — 默认 Keyset 游标分页端点

• 新增 GET /list/keyset 端点（GetKeysetPageAsync），基于 BLL/DAL 的 GetKeysetPageAsync，直接返回 KeysetPage 两段式契约（{ items, pageInfo }）
• 参数：cursor（游标令牌，null 表示首页）、direction（Next/Prev）、pageSize（默认 20），默认按 Id 降序（构建器未声明排序键时自动兜底）
• MethodsEnable 新增 GetKeysetPageAsync 开关控制该端点，与 Offset 分页端点（GET /list/simple）对称

每个端点独立开关

• GetDetailsForAdminAsync（GET {id}/for-admin）拆独立开关 MethodsEnable.GetDetailsForAdminAsync（原复用 GetDetailsAsync）
• GetForAdminEditorAsync（GET {id}/editor/for-admin）拆独立开关 MethodsEnable.GetForAdminEditorAsync（原复用 GetForEditorAsync）
• 至此 WebApiBaseController 全部 18 个端点均拥有独立开关，互不牵连

缓存开关注册（端点级，与 MethodsEnable 同模式）

• 新增 CacheEnableRegistry 静态注册表 + 基类 RegisterCacheEnable<TController>(config)：在控制器静态构造函数中注册 CacheEnable 配置，控制器构造函数自动同步到 BLL.CacheEnable（未注册的控制器为 null，缓存默认关闭）
• CacheEnable 仅控制 API 端点路径（BLL 门面方法）；自定义业务方法显式传 useCache: true/false 三态参数自由控制，两者互不干扰
• 缓存默认关闭（破坏性）：注入 ICacheManager 后端点默认不缓存，需注册 CacheEnable 且对应开关为 true 才缓存——详见 Core Readme 8.5.0 的缓存体系重构说明

---

8.4.0

2026年8月8日 星期六

与 Crping.EFCore / Crping.EFCore.Common 同步升至 8.4.0

• 无功能性变更，仅同步版本号（TimeProvider 注入在 Core 层 BLL/DAL，Controller 透明）

---

8.3.0

2026年8月8日 星期六

与 Crping.EFCore / Crping.EFCore.Common 同步升至 8.3.0

Controller 层健壮性与开关机制完善

• GetCurrentUserId 无 UserId claim 时抛 401（UnauthorizedAccessException，经 ExceptionFilter/Middleware 映射 401），不再返回默认值（int→0 / string→null），避免未登录请求以默认身份执行写操作
• MethodsEnableConvention 启动 WARN 诊断：注入 ILogger，对"未注册配置 / 开关关闭"的端点输出启动日志（新增 DI 扩展 AddMethodsEnableConvention()，替代 options.Conventions.Add(new MethodsEnableConvention())；旧用法仍兼容但无诊断日志）
• 端点自定义路由 RegisterMethodsRoutes<TController>()：在静态构造函数中按开关名注册路由模板（如 CreateAsync → "publish"），开关启用的端点路由改写为注册模板（相对控制器级 [Route] 前缀），未注册路由的端点使用 attribute 默认路由；开关关闭的端点仍被移除
• MethodsEnable 开关解析缓存 + 未知开关名清晰异常（启动时抛出并列出有效开关名，代替 NRE）
• ToggleDeleteStatusAsync 拆独立开关（原复用 SoftDeleteAsync）
• 移除旧 GET /List 端点（GetListAsync）与其 MethodsEnable.GetListAsync 开关——已被 GET List/Offset（GetOffsetPageAsync）替代
• WebApiRootController.MethodsEnable 实例属性改只读（从注册表读取，未注册为 null），移除 setter——旧 Configure() 中设置实例属性的写法编译失败，强制走 RegisterMethodsEnable<TController> 注册
• 删除零引用 MvcController；Utils.Migrate<TDb> / EnsureCreated<TDb> 迁至 Crping.EFCore 包的 DatabaseExtensions（命名空间变更，Breaking）
• ExceptionFilter / ExceptionMiddleware 抽取公共 ExceptionHelper.CreateProblemDetails
• 日志类别对齐注入类型（ILogger<WebApiRootController<...>>）；Convention 仅处理继承自 WebApiRootController<,,,,> 的控制器；清理 Usings 残留

---

8.2.0

2026年8月8日 星期六

与 Crping.EFCore / Crping.EFCore.Common 同步升至 8.2.0

破坏性变更 — 端点启用机制：405 开关 → 启动时移除（IApplicationModelConvention）

• 被禁用的端点不再注册路由（请求返回 404），且不出现在 OpenAPI 文档中；旧机制为方法内返回 405、文档仍可见
• 配置方式由实例 Configure() 改为按控制器类型注册：各控制器静态构造函数调用 RegisterMethodsEnable<TController>(config)（基类 WebApiRootController 提供），由 MethodsEnableConvention 在启动时读取并移除禁用端点
• 新增 MethodEnableAttribute：标注在 WebApiBaseController 各端点方法上，关联开关名；未标注的端点（子类自定义）不受开关控制
• 未注册配置的控制器：带开关特性的端点默认全部移除（与旧行为"默认禁用"语义一致）
• 新增 DI 扩展 AddMethodsEnableConvention()：通过 DI 注入 ILogger，启动时对"未注册配置 / 开关关闭"的端点输出 WARN 诊断日志，避免端点静默 404 难以排查（原 options.Conventions.Add(new MethodsEnableConvention()) 用法仍兼容，但无诊断日志）
• WebApiRootController.MethodsEnable 实例属性改为只读：返回注册表中本控制器类型注册的配置（未注册为 null），与实际生效开关一致；启用以 RegisterMethodsEnable<TController> 注册为准，实例上不可修改（旧 Configure() 中设置实例属性的写法编译失败，强制走新注册方式）

---

8.1.0

2026年8月8日 星期六

与 Crping.EFCore / Crping.EFCore.Common 同步升至 8.1.0

• 无功能性变更，仅同步版本号（分页契约两段式重构在 Common / Core 层；Controller GET /Page 端点返回形状随契约变为 { items, pagination }）

---

8.0.0

2026年8月7日 星期五

与 Crping.EFCore / Crping.EFCore.Common 同步升至 8.0.0

• 无功能性变更，仅同步版本号（BLL 缓存方法新增 useCache 参数对 Controller 调用透明，默认行为不变）

---

7.7.0

2026年8月7日 星期五

与 Crping.EFCore / Crping.EFCore.Common 同步升至 7.7.0

破坏性变更 — 缓存注入切换

• 所有控制器基类（WebApiRootController / MvcController / WebApiBaseController 及其派生）构造参数由 IDistributedCache? 替换为 ICacheManager?，Cache 属性类型同步更新
• 消费者 DI 注册：builder.Services.AddEFCoreRedisCache(redisConfig) 一行完成（IConnectionMultiplexer + ICacheVersionStore + ICacheManager），另需 AddStackExchangeRedisCache 提供业务数据存储（v8.0.0 起方法名由 AddCrpingRedisCache 重命名）

缓存健壮性增强（2026-08-07）

• GET /Details 等投影端点（GetDetailsAsync / GetForEditorAsync / GetListItemAsync / GetSimpleAsync）经 BLL 详情投影缓存生效，键含投影指纹，不同投影互不串扰

---

7.6.0

2026年8月6日 星期四

与 Crping.EFCore / Crping.EFCore.Common 同步升至 7.6.0

Offset 偏移分页端点

• 新增 GET /Page 端点（GetOffsetPageAsync），直接返回 OffsetPage 契约（items + page + pageSize + recordCount + pageCount + hasNext + hasPrev），与 Keyset 响应结构统一
• MethodsEnable 新增 GetOffsetPageAsync 开关控制该端点
• 旧 GET /List 端点（GetListAsync）标记 [Obsolete]，返回形状不变，仍可用

安全加固（2026-08-07）

• 5xx 不再回传异常消息：ExceptionFilter / ExceptionMiddleware 对 statusCode >= 500 的 Detail 置为 null，避免向客户端泄露堆栈 / SQL / 内部实现细节；4xx 仍返回异常消息便于排查

---

7.5.0

2026年8月6日 星期四

与 Crping.EFCore / Crping.EFCore.Common 同步升至 7.5.0

• 无功能性变更，仅同步版本号（Keyset 分页重写在 DAL/BLL 层，Controller 透明）

---

7.4.0

2026年8月3日 星期一

与 Crping.EFCore / Crping.EFCore.Common 同步升至 7.4.0

• 无功能性变更，仅同步版本号

---

7.3.0

2026年7月30日 星期三

与 Crping.EFCore / Crping.EFCore.Common 同步升至 7.3.0

• 无功能性变更，仅同步版本号（底层 BLL 的时间类型变更对 Controller 层透明）

---

7.2.0

2026年7月28日 星期一

与 Crping.EFCore / Crping.EFCore.Common 同步升至 7.2.0

• 无功能性变更，仅同步版本号

---

7.1.0

2026年7月28日 星期一

与 Crping.EFCore 同步升至 7.1.0

新增类（向后兼容 — 旧类标记 [Obsolete]）

• WebApiRootController：控制器根基类，替代 WebApiCoreController（"Core" 名称易与 ASP.NET Core 混淆）
• WebApiIntController：基于 int 类型主键用户的控制器，替代 WebApiForIntController（去掉 "For" 前缀）
• WebApiLongController：基于 long 类型主键用户的控制器，替代 WebApiForLongController

重命名（向后兼容）

• WebApiCoreController → WebApiRootController：旧类保留并继承新类，添加 Dom 属性向后兼容
• WebApiForIntController → WebApiIntController：旧类保留并继承新类
• WebApiForLongController → WebApiLongController：旧类保留并继承新类

---

7.0.0

2026年7月26日 星期日

与 Crping.EFCore 同步升至 7.0.0

清理（破坏性变更 — 文件级）

• 删除 4 个全注释死代码文件（下游若手动引用以下类型会编译失败）：
  • WebApiVersionController.cs（221 行注释，OpenAPI/版本路由相关）
  • SwaggerExt.cs（94 行注释，已被 Crping.ApiDoc.NSwag / Crping.ApiDoc.Scalar 替代）
  • SwaggerOptions.cs（37 行注释）
  • SwaggerFilter.cs（26 行注释）

安全（行为变更 — 建议关注）

• 移除 MvcController 与 WebApiCoreController 中 GetCurrentUserId() 的 #if DEBUG 分支
  • 之前：Debug 构建返回硬编码 "DebugUser"，Release 构建从 JWT claims 读取
  • 现在：始终从 JWT claims 读取 — 生产环境之前若依赖 Debug 构建的"假用户"行为，需要在配置或开发环境中显式 mock；不再有"Debug 即自动拥有任意身份"的隐式行为
  • 这条与 AGENTS.md「反模式」§#if DEBUG 在生产路径中改变用户身份 一致：本次提交已修复

重构

• 提取 ExceptionHelper，ExceptionFilter 的 MapException 逻辑由重复实现改为集中调用，消除 21 行的分散代码

修复

• Utils.Migrate / Utils.EnsureCreated 改用 GetRequiredService<T>() 解析 DbContext / DbContextFactory，之前若服务未注册会静默吞错（null），现在会立即抛 InvalidOperationException

内部（净状态未变）

• IDomain 中未使用的 HTTP 类型依赖相关 refactor（commit 3eb4504）已被回退（65ae448），净状态未变

---

6.10.0

2026年7月14日 星期二

• 剥离 NSwagApiDocExt（移除 AddAuthOpenApiDocument、UseAuthOpenApi 扩展方法），OpenApi 文档生成由独立包 Crping.ApiDoc.NSwag 提供
• 移除 NSwag.AspNetCore 包引用；显式声明 Microsoft.AspNetCore.App 共享框架引用以取代原本寄生于 NSwag 的隐式 FrameworkReference
• 清理不再需要的 Microsoft.AspNetCore.Http.Extensions 与 Microsoft.AspNetCore.Mvc.ViewFeatures 包引用（已被共享框架覆盖）

---

6.9.0

2026年7月7日 星期二

• 新增 WebApiCoreController 可直接被需要轻量控制器的场景使用

---

6.8.0

2026年6月14日 星期日

• 优化异常处理中间件 ExceptionMiddleware
• 优化异常过滤器 ExceptionFilter

---

6.7.0

2026年2月26日 星期三

• 新增授权验证策略类 AuthPolicies，用于控制器方法的授权验证
• 为控制器方法添加管理员权限验证：GetDetailsForAdminAsync 和 GetForAdminEditorAsync 方法添加 [Authorize(AuthPolicies.Admin)] 特性

---

6.6.0

2026年2月6日 星期五

• 新增方法ToggleDeleteStatusAsync

---

6.5.0

2026年2月6日 星期五

• 优化软删除相关方法逻辑
• 新增状态切换方法ToggleEnableStatusAsync, ToggleAuditStatusAsync

---

6.4.0

2025年12月31日 星期三

• 优化所有命名空间

---

6.3.0

2025年12月28日 星期日

• 方法启用控制 MethodsEnable添加更多默认Get方法控制
• WebApiBaseController新增更多Get方法

---

6.1.0

2025年12月25日 星期四

• 将方法禁用控制改为启动控制，默认禁用所有默认方法

---

6.0.0

2025年11月27日 星期四

• 升级为 .net10.0

---

5.1.0

2025年5月23日 星期五

• 新增方法 SoftDeleteAsync(...)

---

5.0.0

2024年11月17日 星期日

• 升级为 .net9.0
• 更新引用组件，并清理替换弃用的组件

---

4.11.0

2024年11月16日 星期六

• 新增类 ExceptionMiddleware，ExceptionFilter

---

4.10.0

2024年11月16日 星期六

• AuthenticationHeaderValue 修改为 AuthHeaderValue
• GetAuthenticationHeaderValue() 修改为 GetAuthHeaderValue()
• 新增类 MethodDisable 以配置默认方法是否可用
• 为所有默认方法添加是否可用的控制

---

4.9.0

2024年11月14日 星期四

• WebApiBaseController 新增方法 GetAuthenticationHeaderValue() 以及属性 AuthenticationHeaderValue

---

4.8.0

2024年11月14日 星期四

• WebApiBaseController 新增方法 GetAuthorization() 以及属性 Authorization

---

4.7.0

2024年10月11日 星期五

• 优化构造方法 WebApiBaseController，并添加对 SyncConfig() 的调用

---

4.5.0

2024年7月17日 星期三

• 新增Migrate()，EnsureCreated(...)

---

4.4.0

2024年4月13日 星期六

• WebApiBaseController新增TDomain，并修改相关子类

---

4.3.0

2024年4月7日 星期日

• 新增领域对象属性DO，并更名_dom_为_do

---

4.2.0

2024年4月7日 星期日

• Controller相关类添加IDomain接口属性_dom_

---

4.1.0

2024年3月28日 星期四

• 新增：WebApiBaseController，WebApiForIntController，WebApiForLongController

---

4.0.0

2024年1月27日 星期六

• 升级目标框架为.net8.0
• 升级Microsoft.Extensions.Configuration.Abstractions为8.0
• 与系列相关组件对齐版本号

---

3.19.0

2023-06-29

• 为所有泛型参数TKey添加约束notnull
• 为MvcController的用户权限操作添加泛型TUserKey，并修改相关属性与方法，并重构GetCurrentUserId()
• 为WebApiController的用户权限操作添加泛型TUserKey，并修改相关属性与方法，并重构GetCurrentUserId()
• 为WebApiVersionController的用户权限操作添加泛型TUserKey，并修改相关属性与方法，并重构GetCurrentUserId()

---

3.18.0

2023-06-05

• 新增跨域管理：CrossDomainSetup

---

3.17.0

2023-05-13

• 新增方法：UseAuthSwaggerWithVersion()

---

3.16.0

2023-04-21

• 方法UseAuthSwagger(...)去除参数，在内部通过DI获取所需数据
• 优化方法AddAuthSwagger(...)

---

3.15.0

2023-04-15

• 项目启动可空类型
• 新增方法：AddApiVersion
• 新增属性：BLL，Logger，Cache，并修改相关方法

---

3.12.0

2023-03-05

• 重命名创建与修改相关API默认方法名

---

3.11.0

2023-02-24

• GetTotalAsync新增参数lastDays

---

3.10.0

2023-02-08

• 新增SwaggerExt类，新增方法AddAuthSwagger，UseAuthSwagger

---

3.9.0

2023-02-03

• 将运行时修改为net7.0

---

3.8.0

2023-01-13

• WebApiController新增方法Task<IActionResult> GetTotalAsync()
• WebApiVersionController新增方法Task<IActionResult> GetTotalAsync()

---

3.7.0

2023-01-03

• 新增全局引用Global，并优化所有引用
• 优化所有命名空间，并更新对组件的引用

---

3.6.1

2022-12-09

• 删除MvcController中默认的Index方法

---

3.6.0

2022-12-09

• 新增MvcController

---

3.5.0

2022-11-23

• 升级Swashbuckle.AspNetCore.SwaggerGen到6.4.0
• 更新对Crping.EFCore 3.9.0的引用，使用EFCore 7.0.0

---

历史版本

• 3.4.1：更新引用组件版本
• 3.4.0：适配Crping.EFCore的更新，删除IRelatedBLL相关方法的使用
• 3.3.0：更新对Crping.EFCore 及 Common的引用，并对齐版本号
• 3.0.1：给方法添加判空逻辑
• 3.0.0：目标框架改为.net6.0
• 2.0.1：升级Swagger相关组件
• 2.0.0：与 Crping.EFCore 2.0 版本号对齐（EFCore 重大改版！！！）
• 1.2.1：更新对Crping.EFCore的引用
• 1.2.0：添加_bll.SetCurrentUserForRelatedBLL(GetCurrentUserId);
• 1.1.0：升级对Crping.EFCore的引用
• 1.0.0：支持普通WebApi，带版本控制WebApi

==注意：==

• Crping.EFCore升级后，此组件需重新打包，保持对Crping.EFCore引用的同步更新，否则会出现“==方法未找到==”的问题