👁 Image
BugFree.Controllers.Core 1.2.2026.616-beta1005

BugFree.Controllers.Core

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

👁 NuGet

特性

📦 统一控制器基类

• 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 许可证开源。