BugFree.Controllers.Core 1.2.2026.807-beta0945

BugFree.Controllers.Core

BugFree 的 ASP.NET Core 控制器基础库，提供统一响应、XCode 实体 CRUD、可组合操作能力、配置控制器、CORS、响应压缩、API 版本控制、IP 访问控制和安全响应头等基础设施。

核心能力

📦 统一控制器基类

• BugFreeController 继承 ControllerBase，统一应用 [Authorize]、[ApiController] 和版本化 API 路由。
• 默认路由为 api/[area]/v{version:apiVersion}/[controller]/[action]。
• 内置 Success() / Fail() / Unauthorized() 及对应异步封装。
• 通过 IResponseService 替换响应构建策略；未注册时自动使用默认实现。

🧩 可组合实体控制器

• EntityController<TEntity, TModel> 在单一基类中提供 Query、Get、Add、Update、Upsert 和 Delete。
• 基于 BugFree.XCode.Extensions 与 XCode ORM；TEntity 必须继承 BugFreeEntity<TEntity> 并实现 IEntity<TModel>。
• ExposeEntityActionsAttribute 可按控制器选择开放的操作，未开放的操作不会进入 MVC 路由和 API Explorer。
• EntityActions 是标志枚举，支持预设值 ReadOnly、Editable、All，也支持任意按位组合。
• 不使用 ExposeEntityActionsAttribute 时，六个标准操作全部开放；未标记 EntityActionAttribute 的自定义 Action 不受能力筛选影响。

⚙️ 配置控制器

• ConfigController<TConfig> 基于 BugFree.Configuration 提供 Get / Save 端点。
• TConfig 必须继承 Config<TConfig> 并具有无参构造函数。

🛡️ 安全中间件

📋 统一响应模型

• Response + ResponseCode 标准化响应码、消息、业务数据和运行时信息。
• RunTimeContext 记录查询次数、执行次数、耗时和 SQL 列表。

🔧 扩展方法

• AddCoreService() 注册内存缓存、CORS、Gzip 响应压缩、API 版本控制和 API Explorer。
• AddBugFreeJsonOptions() 应用统一 JSON 序列化选项，也可传入自定义配置委托。
• GetRemoteIpAddress() / GetRemoteIp() 解析代理头并回退到连接远端地址。
• GetRawUri() 可按代理协议头还原原始请求 URI。

📐 配置选项（基于 BugFree.Configuration，支持热更新）

目标框架

• .NET 8.0
• .NET 10.0

项目通过 FrameworkReference 使用 Microsoft.AspNetCore.App，并针对不同目标框架引用对应版本的 JWT 认证与 API 版本浏览组件。

安装

dotnet add package BugFree.Controllers.Core

或通过 NuGet 包管理器搜索 BugFree.Controllers.Core。

快速开始

1. 注册服务和中间件

在 Program.cs 中：

using BugFree.Controllers.Core.Middleware;
using BugFree.Controllers.Extensions;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers()
    .AddBugFreeJsonOptions();

// 内存缓存、CORS、Gzip、API 版本控制和 API Explorer
builder.Services.AddCoreService();

var app = builder.Build();

app.UseResponseCompression();
app.UseCors();
app.UseMiddleware<IpAccessControlMiddleware>();
app.UseMiddleware<SecurityResponseHeaderMiddleware>();

// 认证与授权由宿主应用按实际方案注册并加入管道。
app.MapControllers();

app.Run();

AddCoreService() 负责注册服务，UseResponseCompression()、UseCors() 和两个安全中间件仍需由宿主显式加入请求管道。由于 BugFreeController 带有 [Authorize]，宿主还必须配置可用的认证与授权方案。

2. 创建完整实体控制器

先准备 XCode 实体和输入输出模型。泛型必须满足以下关系：

// TEntity : BugFreeEntity<TEntity>, IEntity<TModel>, new()
// IEntity<TModel>.Copy(TModel model) 负责模型到实体的映射。

继承 EntityController<TEntity, TModel>；未指定能力特性时默认开放全部六个操作：

using BugFree.Controllers.Core.Basis;

using Microsoft.AspNetCore.Mvc;

[Area("System")]
public sealed class UserController : EntityController<UserEntity, UserModel>
{
    public UserController(IServiceProvider serviceProvider) : base(serviceProvider) { }
}

生成的路由形如：/api/System/v1/User/Query。新增、更新和保存成功后，响应中的 data 是写入后的原模型，数据库生成的主键或默认值会复制回该模型。

3. 选择开放的实体操作

只读控制器不再需要另一套继承层次，直接声明能力：

using BugFree.Controllers.Core.Attributes;

[Area("System")]
[ExposeEntityActions(EntityActions.ReadOnly)]
public sealed class ReadOnlyUserController : EntityController<UserEntity, UserModel>
{
    public ReadOnlyUserController(IServiceProvider serviceProvider) : base(serviceProvider) { }
}

也可以任意组合，例如只开放列表查询和新增：

[Area("System")]
[ExposeEntityActions(EntityActions.Query | EntityActions.Add)]
public sealed class UserImportController : EntityController<UserEntity, UserModel>
{
    public UserImportController(IServiceProvider serviceProvider) : base(serviceProvider) { }
}

被关闭的标准操作会从 MVC 应用模型中移除，因此不会进入路由和 API Explorer；派生控制器自行定义且未标记 EntityActionAttribute 的 Action 不受影响。

4. CRUD 行为

Upsert 只判断唯一键是否为 null。空字符串、0、Guid.Empty 等非 null 值都会进入更新路径。

软删除实体若使用“非主键字符串唯一键”，删除时会给原唯一键追加随机后缀，以释放原唯一值。

5. 配置控制器

using BugFree.Controllers.Core.Basis;

using Microsoft.AspNetCore.Mvc;

[Area("System")]
public sealed class AppConfigController : ConfigController<AppConfigOptions>
{
    public AppConfigController(IServiceProvider serviceProvider) : base(serviceProvider) { }
}

配置说明

IP 访问控制

在配置文件（如 appsettings.json）中：

{
  "AccessDecisionRules": {
    "Allows": {
      "Enabled": true,
      "IpRules": ["192.168.1.0/24", "10.0.0.1-10.0.0.100", "114.114.114.114"]
    },
    "Denies": {
      "Enabled": true,
      "IpRules": ["0.0.0.0/8", "10.0.0.5"]
    }
  }
}

• IpAccessControlMiddleware 当前按 Deny → Allow → 默认放行 的顺序判断；同一 IP 同时命中两组规则时会拒绝。
• 未命中 Allows 不会自动拒绝，因此当前 Allows 不是“必须命中的白名单”。
• 支持：单 IP、CIDR（192.168.1.0/24）、IP 范围（10.0.0.1-10.0.0.100）
• DynamicEvaluator 可在静态规则未命中时执行程序化判断；该委托不会从 JSON 配置反序列化。

CORS 域名控制

{
  "CorsOriginRules": {
    "Enabled": true,
    "AllowedDomains": ["example.com", "*.example.com"]
  }
}

支持精确域名和 *.example.com 形式的子域名通配符。配置未启用或列表为空时允许所有来源；使用 AllowCredentials() 时应仅配置可信来源。

安全响应头

{
  "ResponseHeader": {
    "Enabled": true,
    "RemoveHeaders": ["X-AspNet-Version", "X-AspNetMvc-Version"],
    "XFrameOptions": "SAMEORIGIN",
    "StrictTransportSecurity": "max-age=31536000; includeSubDomains",
    "ContentSecurityPolicy": "default-src 'self'; script-src 'self'"
  }
}

SecurityResponseHeaderMiddleware 还支持 Referrer-Policy、COOP、CORP、可选 COEP 和安全策略报告端点。Debug 构建默认关闭，非 Debug 构建默认开启；RemoveHeaders 在响应开始前最后执行，具有最终移除优先级。

响应格式

由 BugFreeController 构建的成功和失败结果统一使用 Response 结构：

{
  "code": 200,
  "message": "执行成功",
  "data": {
    "id": 1,
    "name": "示例"
  },
  "runtime": null
}

下表列出 ResponseCode 可表达的状态。当前 EntityController 的六个标准操作成功时统一使用业务码 200；201、204 等枚举值需由自定义响应策略或业务控制器显式采用。

IpAccessControlMiddleware 在拒绝请求时直接返回 HTTP 403 和纯文本 Access Denied，不经过统一 Response 包装。

主要依赖

项目结构

BugFree.Controllers.Core/
├── Abstractions/
│   └── Application/        ← 响应服务接口
├── Core/
│   ├── Attributes/         ← 实体能力、缓存和日志分类特性
│   ├── Basis/              ← BugFree、实体和配置控制器基类
│   ├── Middleware/         ← IP 访问控制和安全响应头中间件
│   └── Shared/             ← 默认响应服务与 MVC 元数据解析
├── Extensions/             ← 服务注册、JSON 和 HttpContext 扩展
├── Models/
│   ├── Requests/           ← 请求模型（Page）
│   └── Responses/          ← 响应模型（Response, RunTimeContext）
├── Options/                ← IP、CORS、响应头、分页和 Redis 配置
└── docs/                   ← 设计资料

许可

项目的 NuGet 包许可证声明为 MIT，见 Directory.Build.props。