# magic-api-plugin

**Repository Path**: sirius/magic-api-plugin

## Basic Information

- **Project Name**: magic-api-plugin
- **Description**: 整理一下，自己写的一些magic-api的插件
- **Primary Language**: Java
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 25
- **Forks**: 20
- **Created**: 2023-01-22
- **Last Updated**: 2026-09-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Magic API 插件集合

## 项目介绍

Magic API 插件集合是一系列为 Magic API 框架开发的功能扩展插件，旨在增强 Magic API 的能力，提供更多实用功能。这些插件涵盖了网关集成、监控、服务注册与发现、远程调用、认证授权和流量控制等多个方面。

## 插件列表

### 1. magic-api-plugin-monitor-starter
**功能**：为 Magic API 提供 Prometheus 监控能力
- JVM 指标：内存使用、GC 次数、线程状态等
- HTTP 指标：API 调用次数、响应时间、错误率等
- 系统指标：CPU 使用率、磁盘使用等

### 2. magic-api-plugin-nacos-starter
**功能**：为 Magic API 提供 Nacos 集成功能
- 配置获取：从 Nacos 配置中心获取配置信息
- 服务注册：将 Magic API 服务注册到 Nacos 服务发现
- 集群同步：利用 Nacos 配置监听实现 Magic API 集群间的接口配置同步

### 3. magic-api-plugin-rpc-starter
**功能**：基于 Dubbo 的远程调用插件
- 服务注册与发现：将 Magic API 接口注册为 Dubbo 服务，支持服务发现
- 动态管理：支持运行时修改和热更新 RPC 服务
- 泛化调用：基于 Dubbo 泛化接口，无需生成客户端代码
- 可视化管理：提供直观的前端管理界面
- 依赖 Nacos 插件提供服务注册和发现功能

### 4. magic-api-plugin-satoken-starter
**功能**：Magic-API 的 SaToken 鉴权插件
- LOCAL 模式：使用 Sa-Token 进行本地鉴权
- OAUTH2CLIENT 模式：作为 OAuth2 客户端对接外部认证服务
- 权限校验：支持基于角色和权限的细粒度控制
- Bearer Token：支持从 Authorization 头获取 token

### 5. magic-api-plugin-sentinel-starter
**功能**：基于 Sentinel 的限流与熔断插件
- 流量控制：支持基于 QPS 和线程数的限流，多种流控模式
- 熔断降级：支持 RT、异常比例、异常数三种熔断策略
- 热点参数限流：对热点参数进行精确限流
- 系统保护：基于系统负载、CPU 使用率等指标的系统保护
- 授权规则：支持白名单和黑名单的授权控制
- 控制台集成：支持与 Sentinel 控制台集成，实现规则的动态配置
- 脚本函数：在 Magic API 脚本中使用 Sentinel 相关功能

### 6. magic-api-plugin-seata-starter
**功能**：基于 Seata 的分布式事务插件（独立 seata-server，注册中心走 Nacos）
- 全局事务管控：脚本里以程序化方式开启 / 提交 / 回滚 Seata 全局事务
- 脚本模块：提供 `seata.begin / commit / rollback / status / currentXid / transaction` 等函数
- 闭包语法糖：`seata.transaction(name, () => {...})` 自动提交、异常自动回滚
- TM 侧集成：事务生命周期交给 Seata 客户端，TC 独立部署、通过 Nacos 做注册中心
- 同线程自动传递：xid 通过 Seata RootContext 在当前线程内自动传递，串联 db / liteflow / 本地调用
- AT 模式自动代理：应用就绪后自动把 Magic API 的数据源包成 Seata DataSourceProxy，脚本里的 db 操作无感接入 AT 全局事务（可选开关 + 排除列表）
- 跨服务传播（M3）：调用方 `seata.getXid()` 取 xid 塞进下游请求头，下游由入站拦截器自动 bind 加入全局事务；Dubbo 调用由 Seata 过滤器自动透传 attachment；脚本另提供 `bind / unbind / xidHeader` 手动接管

## 版本要求

- Java 17+
- Spring Boot 3.4.9+
- Magic API 2.2.2+

## 安装方法

### Maven 依赖

```xml
<!-- 选择需要的插件添加依赖 -->
<!-- 监控插件 -->
<dependency>
    <groupId>org.ssssssss</groupId>
    <artifactId>magic-api-plugin-monitor-starter</artifactId>
    <version>2.2.2</version>
</dependency>

<!-- Nacos 插件 -->
<dependency>
    <groupId>org.ssssssss</groupId>
    <artifactId>magic-api-plugin-nacos-starter</artifactId>
    <version>2.2.2</version>
</dependency>

<!-- RPC 插件 -->
<dependency>
    <groupId>org.ssssssss</groupId>
    <artifactId>magic-api-plugin-rpc-starter</artifactId>
    <version>2.2.2</version>
</dependency>

<!-- SaToken 插件 -->
<dependency>
    <groupId>org.ssssssss</groupId>
    <artifactId>magic-api-plugin-satoken-starter</artifactId>
    <version>2.2.2</version>
</dependency>

<!-- Sentinel 插件 -->
<dependency>
    <groupId>org.ssssssss</groupId>
    <artifactId>magic-api-plugin-sentinel-starter</artifactId>
    <version>2.2.2</version>
</dependency>

<!-- Seata 分布式事务插件 -->
<dependency>
    <groupId>org.ssssssss</groupId>
    <artifactId>magic-api-plugin-seata-starter</artifactId>
    <version>2.2.2</version>
</dependency>
```

### Gradle 依赖

```gradle
// 选择需要的插件添加依赖
// 监控插件
implementation 'org.ssssssss:magic-api-plugin-monitor-starter:2.2.2'

// Nacos 插件
implementation 'org.ssssssss:magic-api-plugin-nacos-starter:2.2.2'

// RPC 插件
implementation 'org.ssssssss:magic-api-plugin-rpc-starter:2.2.2'

// SaToken 插件
implementation 'org.ssssssss:magic-api-plugin-satoken-starter:2.2.2'

// Sentinel 插件
implementation 'org.ssssssss:magic-api-plugin-sentinel-starter:2.2.2'
```

## 插件配置

### Nacos 插件配置

**前置条件**：`spring.application.name` 必须配置，否则服务注册名会显示为 `unknown`。

```yaml
spring:
  application:
    name: your-service-name  # 必填，Nacos 中注册的服务名

magic-api:
  nacos:
    enable-config: false        # 是否开启配置管理
    enable-discovery: true      # 是否开启服务注册与发现
    enable-cluster: false       # 是否开启集群同步（基于配置监听，有 1~3s 延迟）
    enable-start-config: false  # 是否开启启动时获取配置
    server-addr: 127.0.0.1:8848 # Nacos 服务地址
    group: DEFAULT_GROUP        # 配置分组，默认 DEFAULT_GROUP
    service-name: my-service    # 服务名（可选，默认读取 spring.application.name）
    cluster-name: DEFAULT       # 集群名
    namespace: ""               # 命名空间，为空使用默认命名空间
    # 以下为鉴权配置（Nacos 开启鉴权时需要）
    enable-auth: true
    username: nacos
    password: nacos
```

**配置说明**：

| 配置项 | 必填 | 默认值 | 说明 |
|--------|------|--------|------|
| `enable-config` | 否 | false | 开启后从 Nacos 获取配置 |
| `enable-discovery` | 否 | false | 开启后注册服务到 Nacos |
| `enable-cluster` | 否 | false | 开启后启用集群同步（基于配置监听，有 1~3s 延迟） |
| `enable-start-config` | 否 | false | 开启后启动时从 Nacos 拉取配置 |
| `server-addr` | 是 | - | Nacos 服务器地址 |
| `group` | 否 | DEFAULT_GROUP | 配置分组 |
| `service-name` | 否 | spring.application.name | 注册到 Nacos 的服务名 |
| `cluster-name` | 否 | DEFAULT | 集群名称 |
| `namespace` | 否 | "" | 命名空间 ID |
| `enable-auth` | 否 | false | 是否开启鉴权 |
| `username` | 否 | - | 鉴权用户名 |
| `password` | 否 | - | 鉴权密码 |

### Seata 插件配置

**前置条件**：已独立部署 seata-server（TC），并让它和本服务连同一个 Nacos 做注册中心。

```yaml
magic-api:
  seata:
    enabled: true                  # 总开关（默认开启），关闭后脚本里 import seata 不可用
    at-datasource-enabled: true    # AT 模式自动数据源代理（默认开启），把 Magic API 的数据源包成 Seata DataSourceProxy
    exclude-datasources: ""        # 不参与 AT 的数据源 key 列表（逗号分隔），如 "local,readonly"

seata:
  enabled: true
  application-id: ${spring.application.name}   # 参与方应用名，建议与 Nacos 服务名一致
  tx-service-group: my_test_tx_group          # 事务分组，需与 seata-server 的 vgroup 映射一致
  registry:
    type: nacos
    nacos:
      server-addr: 127.0.0.1:8848
      group: SEATA_GROUP
      namespace: ""
  config:
    type: nacos
    nacos:
      server-addr: 127.0.0.1:8848
      group: SEATA_GROUP
  service:
    vgroup-mapping:
      my_test_tx_group: default               # default 对应 seata-server 的 cluster 名
    grouplist:
      default: 127.0.0.1:8091                 # seata-server 的 TC 地址（registry 用 nacos 时可省略）
```

**使用方式**（脚本里）：

```js
import seata;
// 闭包语法糖：自动提交 / 异常回滚
seata.transaction("create-order", () => {
    db.update("insert into t_order ...");
    liteflow.execute("/liteflow/deduct");   // 同线程内自动共享 xid
});
```

**跨服务传播 xid（M3）**：

- **同线程（脚本里的 db / liteflow / 本地调用）**：`RootContext` 是 ThreadLocal，`transaction` 闭包内天然在同一全局事务，无需任何处理。
- **调下游 HTTP 服务**：调用方把当前 xid 放进请求头，下游自动加入。脚本里：
  ```js
  import seata;
  // 调用方：把 xid 塞进下游请求头（头名默认 TX_XID，可用 magic-api.seata.xid-header 改）
  http.post("http://svc-b/api/order/create")
       .header(seata.xidHeader(), seata.getXid())
       .body({...})
       .call();
  ```
  下游若是本插件（默认 `xid-auto-bind: true`），`SeataXidRequestInterceptor` 会在请求处理前
  自动 `RootContext.bind(xid)`、处理完 `unbind`，使下游的 db / liteflow 自动加入上游全局事务。
  下游若关掉了 `xid-auto-bind`，也可在脚本里手动 `seata.bind(header("TX_XID"))`。
- **调下游 Dubbo 服务**：Seata 的 `SeataDubboFilter` 在 dubbo 在 classpath 时自动把 xid 透传
  到 attachment，无需插件处理（前提是 rpc 插件用的是 Dubbo 且 Seata 的 Dubbo 过滤器已生效）。

脚本里还可直接操作 xid：`seata.getXid()` / `seata.currentXid()` 取当前 xid；
`seata.bind(xid)` / `seata.unbind()` 用于手动接管（被调方加入上游事务的兜底）。

> **AT 模式自动数据源代理（M2，默认开启）**：插件在应用就绪后，会把 `MagicDynamicDataSource`
> 里每个物理数据源用 `io.seata.rm.datasource.DataSourceProxy` 重新注册一遍，节点内部的
> `JdbcTemplate` / `TransactionManager` 会基于代理重建。这样脚本里 `db.xxx` 的 SQL 就会自动
> 记录 `undo_log`、注册分支，无感接入 AT 全局事务。
> - 若你已把数据源定义成 Spring `@Bean` 并被 Seata 自带代理包过，可设 `at-datasource-enabled: false` 关掉本插件代理，避免重复包装。
> - 不想参与 AT 的库（本地库、只读库）用 `exclude-datasources` 排除。
> - **每个参与 AT 的库都必须建 `undo_log` 表**（建表语句见 Seata 官方文档）。
> - 默认数据源的选择依赖 `order`，插件会原样保留各节点的 order（只读反射获取），不影响默认库。
> - 已知待联调验证：Magic API 若对数据源做懒加载（首次 db 调用才注册），则本代理可能在注册前执行，
>   需改为监听对应的注册时机；另外若 Magic API 通过独立的 default 字段持有默认数据源引用，也需一并替换。
> - 入站 xid 绑定只覆盖 **Magic API 的接口请求**；下游若是普通 Spring Controller，需依赖 Seata
>   自带的 Web 过滤器或手动 `seata.bind(xid)`。
> TCC / SAGA 模式不依赖数据源代理，始终可用。

## 项目结构

```
magic-api-plugin/
├── magic-api-plugin-monitor-starter/          # 监控插件
├── magic-api-plugin-nacos-starter/            # Nacos 集成插件
├── magic-api-plugin-rpc-starter/              # RPC 远程调用插件
├── magic-api-plugin-satoken-starter/          # SaToken 鉴权插件
├── magic-api-plugin-sentinel-starter/         # Sentinel 限流熔断插件
├── magic-api-plugin-seata-starter/             # Seata 分布式事务插件
├── .gitignore
├── LICENSE
├── README.en.md
└── README.md
```

## 版本历史

| 版本 | 日期 | 变更内容 |
|------|------|----------|
| 2.2.2 | 2026-09-28 | Seata 插件升级至 Apache Seata 2.6.0（groupId 由 io.seata 改为 org.apache.seata，API 兼容） |
| 2.2.2 | 2026-09-28 | Seata 插件 M3：新增 xid 跨服务传播（入站 xid 自动绑定拦截器 + getXid/bind/unbind/xidHeader 脚本方法） |
| 2.2.2 | 2026-09-24 | Seata 插件 M2：新增 AT 模式自动数据源代理（MagicDynamicDataSource 包装为 Seata DataSourceProxy） |
| 2.2.2 | 2026-09-24 | 新增 Seata 分布式事务插件（M1：全局事务脚本模块 + 自动配置） |
| 2.2.2 | 2026-06-20 | Nacos 插件：添加 enable-cluster 独立开关，修复 Bean 注册问题，更新文档 |
| 2.2.2 | 2026-06-05 | 项目优化：修复 P0/P1/P2 问题、添加单元测试、统一 properties 版本管理 |
| 2.2.2 | 2026-04-09 | 项目整理，添加多个插件 |
| 2.2.2 | 2026-04-06 | 添加 Higress 插件 |
| 2.2.2 | 2026-03-27 | 优化 Nacos 插件 |
| 2.2.2 | 2026-03-20 | 添加 RPC 插件 |
| 2.2.2 | 2026-03-15 | 添加 SaToken 插件 |
| 2.2.2 | 2026-03-10 | 添加 Sentinel 插件 |
| 2.2.2 | 2026-03-05 | 添加监控插件 |

## 注意事项

1. **版本兼容性**：确保使用与 Magic API 版本兼容的插件版本
2. **依赖关系**：RPC 插件依赖 Nacos 插件提供服务注册和发现功能
3. **配置管理**：每个插件都有自己的配置项，请参考各插件的 README.md 文件
4. **性能考虑**：在生产环境中，请注意合理配置插件参数，避免影响系统性能
5. **安全性**：对于涉及认证和授权的插件，请确保正确配置安全参数

## 优化内容

### 工程结构优化
- ✅ 每个子模块独立构建，parent 统一指向 `org.ssssssss:magic-api-plugins`
- ✅ 每个子模块 `pom.xml` 使用 `<properties>` 统一管理版本号
- ✅ 清理注释掉的依赖（nacos-starter 中的 fastjson）

### P0 问题修复
- ✅ SaToken 配置类添加 `@ConditionalOnProperty` 条件注解，未配置时不加载
- ✅ Dubbo 服务注册添加 Nacos namespace 支持，修复多环境部署问题

### P1 问题修复
- ✅ satoken 模块包名 `Interceptor` → `interceptor`，符合 Java 命名规范
- ✅ 补全所有模块的 `spring.factories`（EnableAutoConfiguration）

### P2 问题修复
- ✅ Sentinel 配置类提取重复代码，新增 `createFlowRule()`、`createDegradeRule()` 方法
- ✅ HigressRouteSyncService 提取 `applyAuth()` 方法，消除认证代码重复

### 测试与文档
- ✅ 添加 Sentinel 插件示例单元测试
- ✅ 更新 README.md 版本信息一致性