BugFree.Controllers.Core 1.2.2026.623-beta1237

BugFree.Controllers.Core

BugFree 控制器核心框架，提供统一的 API 控制器基类体系、实体 CRUD 控制器、安全中间件、IP 访问控制、安全响应头注入等开箱即用的企业级 ASP.NET Core 基础设施。

特性

📦 统一控制器基类

• BugFreeController — 继承 ControllerBase，内置 Success() / Fail() / Unauthorized() 快捷响应方法
• 统一 IResponseService 可替换策略，支持自定义响应构建行为

🧩 实体控制器层次体系

BugFreeController
  └── EmptyEntityController<TEntity>          ← 实体工厂初始化
        └── QueryEntityController<TEntity>    ← 列表查询 (Query)
              └── GetEntityController<TEntity> ← 单实体查询 (Get)
                    └── ReadOnlyEntityController<TEntity> ← 只读
                          └── EntityController<TEntity,TModel> ← 完整 CRUD

• 基于 BugFree.XCode.Extensions + NewLife.XCode ORM
• 支持 Add / Update / Upsert / Delete / Get / Query 标准操作
• 泛型约束确保类型安全，支持任意 XCode 实体类

⚙️ 配置控制器

• ConfigController<TConfig> — 基于 BugFree.Configuration 的配置热更新控制器
• 开箱即用的配置 Get/Save API 端点

🛡️ 安全中间件

📋 统一响应模型

• Response + ResponseCode — 标准化的 API 响应结构（Success / Fail / 401 / 403 / 500 等）
• RunTimeContext — 运行时执行统计信息（SQL 次数、耗时、语句列表）

🔧 扩展方法

• AddCoreService() — 一键注册 CORS、缓存、响应压缩、API 版本控制
• AddBugFreeJsonOptions() — 统一 JSON 序列化选项（驼峰命名、忽略 null、默认转换器）
• GetClientIpAddress() — 支持反向代理的客户端 IP 提取（X-Forwarded-For / X-Real-IP 等）

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

目标框架

• .NET 8.0 — 含 Microsoft.AspNetCore.Authentication.JwtBearer + Asp.Versioning.Mvc.ApiExplorer
• .NET 10.0 — 同上最新版

安装

dotnet add package BugFree.Controllers.Core

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

快速开始

1. 注册核心服务

在 Program.cs 中：

using BugFree.Controllers.Extensions;

var builder = WebApplication.CreateBuilder(args);

// 添加控制器
builder.Services.AddControllers()
       .AddBugFreeJsonOptions();  // 统一 JSON 序列化

// 添加 BugFree 核心服务（CORS、缓存、压缩、API 版本控制）
builder.Services.AddCoreService();

2. 创建实体控制器

定义实体和模型（基于 XCode）：

// 实体类
public class UserEntity : BugFreeEntity<UserEntity>, IEntity<UserDto>, new()
{
    public String Name { get; set; }
    public Int32 Age { get; set; }
}

// DTO 类
public class UserDto : IModel
{
    public String Name { get; set; }
    public Int32 Age { get; set; }
}

继承 EntityController 获得完整 CRUD：

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

    // 已自动包含：Add / Update / Upsert / Delete / Get / Query
}

3. 只读控制器

[Area("System")]
public class UserController : ReadOnlyEntityController<UserEntity>
{
    public UserController(IServiceProvider serviceProvider) : base(serviceProvider) { }

    // 已自动包含：Get / Query
}

4. 配置控制器

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

    // 已自动包含：Get / Save
}

配置说明

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"]
    }
  }
}

• Allow 优先于 Deny
• 支持：单 IP、CIDR（192.168.1.0/24）、IP 范围（10.0.0.1-10.0.0.100）
• 支持 DynamicEvaluator 动态扩展

CORS 域名控制

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

安全响应头

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

提示：开发环境默认不启用安全响应头，生产环境自动启用。

响应格式

所有 API 返回统一格式的 Response 结构：

{
  "code": 200,
  "message": "执行成功",
  "data": { ... },
  "runtime": null
}

依赖

项目结构

BugFree.Controllers.Core/
├── Abstractions/           ← 接口定义（IResponseService）
├── Attributes/             ← 特性（SignatureAttribute）
├── Core/
│   ├── Application/        ← 默认响应服务实现
│   ├── Basis/              ← 控制器基类体系
│   ├── Contexts/           ← 属性上下文
│   └── Middleware/         ← 中间件
├── Extensions/             ← 扩展方法（DI 注册、HttpContext）
├── Models/
│   ├── Requests/           ← 请求模型（Page）
│   └── Responses/          ← 响应模型（Response, RunTimeContext）
└── Options/                ← 配置选项

许可

本项目基于 MIT 许可证开源。