API 配置管理（forge-starter-api-config）

API 端点自动注册与动态配置模块，支持启动时扫描 Controller 并自动注册到数据库，提供两级缓存和实时刷新能力。

快速开始

1. 引入依赖

<dependency>
    <groupId>com.mdframe.forge</groupId>
    <artifactId>forge-starter-api-config</artifactId>
</dependency>

2. 自动注册

模块启动时会自动扫描所有 Controller，将端点注册到 sys_api_config 表。

核心功能

自动注册

ApiConfigAutoRegistrar 在启动时通过 RequestMappingHandlerMapping 扫描所有 REST 端点，并解析以下标志位：

标志位	说明	解析方式
`authFlag`	是否需要认证	根据 `@ApiPermissionIgnore` / `@IgnoreTenant` 等注解推断
`encryptFlag`	是否需要加解密	根据 `@ApiEncrypt` / `@ApiDecrypt` 注解推断
`tenantFlag`	是否启用租户隔离	根据 `@IgnoreTenant` 注解推断
`limitFlag`	是否启用限流	根据 `@RateLimiter` 等注解推断

注册时会自动对比数据库中已存在的配置，增量更新。

两级缓存

API 配置查询采用 L1 + L2 两级缓存：

级别	存储	最大容量	过期时间
L1	Caffeine（本地）	1000	10 分钟
L2	Redis	-	30 分钟

查询优先级：L1 → L2 → 数据库

缓存预热

启动时自动预热所有已启用的 API 配置到缓存：

forge:
  api-config:
    cache-warm-up: true

实时刷新

支持通过 Spring Event 实时刷新 API 配置：

修改数据库 → 发布 ApiConfigRefreshEvent → 清除缓存 → 重新加载

数据库表

`sys_api_config`

字段	说明
`api_name`	API 名称（如 "查询用户列表"）
`api_code`	API 编码（唯一标识）
`req_method`	请求方法（GET/POST/PUT/DELETE）
`url_path`	请求路径（如 "/api/user/page"）
`auth_flag`	是否需要认证（0/1）
`encrypt_flag`	是否加解密（0/1）
`tenant_flag`	是否租户隔离（0/1）
`limit_flag`	是否限流（0/1）
`sensitive_fields`	敏感字段列表（JSON）
`status`	状态（0=禁用，1=启用）
`module_code`	所属模块编码
`service_id`	所属服务 ID

REST API

方法	路径	说明
GET	`/api/api-config/page`	分页查询 API 配置
GET	`/api/api-config/{id}`	获取 API 配置详情
PUT	`/api/api-config`	更新 API 配置
POST	`/api/api-config/refresh`	手动触发配置刷新
POST	`/api/api-config/cache/clear`	清除所有缓存
GET	`/api/api-config/cache/stats`	获取缓存统计信息

配置项

forge:
  api-config:
    enabled: true
    auto-register: true
    cache-warm-up: true
    scan-packages: []  # 自定义扫描包路径（为空则扫描全部）
    cache:
      local:
        max-size: 1000
        expire-minutes: 10
      redis:
        enabled: true
        expire-seconds: 1800
        key-prefix: "api:config:"

核心组件

组件	说明
`ApiConfigScanner`	扫描 `RequestMappingHandlerMapping` 发现 API 端点
`ApiConfigAutoRegistrar`	自动注册 API 到数据库
`IApiConfigManager`	API 配置管理接口
`ApiConfigManagerImpl`	实现类（支持数据库 > 注解 > 默认的优先级查询）
`ApiConfigContextHolder`	ThreadLocal 上下文持有者
`ApiConfigRefreshListener`	监听配置刷新事件

使用场景

运行时权限判断

@Autowired
private IApiConfigManager apiConfigManager;

public boolean needAuth(String urlPath, String method) {
    return apiConfigManager.needAuth(urlPath, method);
}

获取所有已启用的配置

List<SysApiConfig> configs = apiConfigManager.getAllEnabledConfigs();

api-config.md 3.9 KB Vēsture Neapstrādāts