API策略页面内置了25种API策略，可实现路由，API接口，订阅关系粒度的API拦截管控。
发布到APIGateway Server上的API可配置全部策略。
发布到ESB Server上的API可配置Basic认证、数字签名、Token认证、请求频次、请求超时、请求体限流、数据脱敏、黑白名单、日志存储9种策略。
具体策略使用详情请参考 API策略说明 。
# 策略类型
管理人员登录系统，进入管理门户，点击菜单“安全管理”>"API策略“，进入API策略页面，默认展示策略类型页签。 策略类型包含：认证策略、流量控制、数据处理、访问控制、日志策略类型。API策略的应用对象为API，路由，订阅关系。
应用对象为API粒度的策略管控
应用对象为路由的策略管控(注意：发布到GATEWAYServer上的接口可配置路由策略)
应用对象为订阅关系的策略管控
# 策略添加应用对象的限制
1认证策略：一个API只能被认证策略下的某一种认证策略类型的一个策略关联，例如：test接口被Basic认证策略的策略A关联，则test接口无法被Basic认证策略的策略B关联，也无法被Token认证策略的策略1关联。路由、订阅关系和API的限制一致。
2其他策略：一个API只能被一种策略类型的一个策略关联，例如：test接口被流量控制策略的策略A关联，则test接口无法被流量控制策略的策略B关联，但是test接口还可以被请求体限流策略的策略1关联。路由、订阅关系和API策略的限制一致。
# 策略的优先级
策略的控制优先级是“订阅关系>API>路由”。
以Basic认证策略为例，新建三个Basic认证策略（策略A、策略B、策略C），现在有一个已发布接口（test接口），test接口被consumer1和consumer2两个系统订阅，为策略A的订阅关系应用对象添加test接口-consumer1订阅关系，在策略B的API应用对象添加test接口，在策略C的路由应用对象添加test接口的所属路由。在调用test接口时，如果消费方是consumer1则策略A生效，其他消费方调用test接口时则策略B生效，如果策略B的API应用对象删除了test接口，其他消费方调用接口时则策略C生效。
# 所属系统
管理人员登录系统，进入管理门户，点击菜单“安全管理”>"API策略“，进入API策略页面，选择策略类型右侧的所属系统页签，可查看各个系统下所有策略。
在“所属系统”页签，选择需要查看的系统，右侧将展示该系统下所有策略。
右侧展示的API策略列表，点击操作栏下的“编辑”按钮，编辑策略完成后，点击“保存”按钮。
右侧展示的API策略列表，点击操作栏下的“删除”按钮，点击“确定”按钮后，即可删除策略。
# 自定义策略操作手册
适用版本：iPaaS Portal 9.1.0 / API Gateway 9.1.0 适用对象：需要在管理端自定义网关插件、并为该插件创建和绑定 API 策略的管理人员与开发者。
# 1. 概述
网关基于 Spring Cloud Gateway 构建，所有请求拦截逻辑都由 过滤器（Filter） 完成。自定义策略的能力链路如下：
开发者在网关侧开发自定义插件（GatewayFilterFactory）
↓ 打包部署到网关 lib/
管理员在 iPaaS Portal 注册"插件"记录（插件编码 = 过滤器名）
↓ 插件编码必须与代码中的策略类型名一致
管理员为插件配置"插件元数据"（定义策略配置表单的字段）
↓ 元数据字段 = 网关过滤器拦截规则的配置项
管理员基于该插件创建"API 策略"（填写策略配置表单的值）
↓ 策略配置 = 过滤器运行时读取的参数
管理员将策略绑定到 路由 / API / 订阅关系
↓ 网关下发策略到过滤器缓存
请求到达 → 过滤器读取策略参数 → 执行拦截逻辑
# 1.1 关键概念
| 概念 | 说明 |
|---|---|
| 插件 | 对应网关的 GatewayFilterFactory。网关 FilterFactory 的类名命名规则必须是 插件编码 + GatewayFilterFactory（例如插件编码为 CustomPolicy，则类名为 CustomPolicyGatewayFilterFactory）。 |
| 插件元数据 | 描述策略配置表单的每一个字段。元数据的字段就是网关 Filter 拦截规则的配置项，也对应策略配置 JSON 中的 key。 |
| API 策略 | 基于某个插件创建的策略实例。策略的配置项由插件的元数据决定，策略的具体取值由管理员填写。 |
| 策略类型名 | 贯穿整条链路的唯一标识。它必须三处保持完全一致：策略缓存类 @Component("X") 的值、getPolicyType() 返回值、过滤器中查询策略时传入的字符串。管理端注册插件时，插件编码必须等于这个策略类型名。 |
# 1.2 插件与策略的关系
- 插件的"类别" 对应 策略类型分组（认证策略、流量控制、数据处理、访问控制、日志策略）。API 策略管理页面左侧的策略类型树就是由"分组插件（typeCode=2）"和其下"具体插件（typeCode=0）"两级构成的。
- 插件的状态：只有状态为"开启"的插件，才会在 API 策略管理页面显示并可用；状态为"关闭"的插件在 API 策略管理页面不显示。
- 是否启用元数据：开启后才能在操作列使用"插件元数据"管理；元数据决定了策略配置表单长什么样。
# 2. 整体流程一览
| 步骤 | 操作位置 | 角色 | 产出 |
|---|---|---|---|
| ① 开发网关自定义插件 | 网关工程 | 开发者 | 插件 jar |
| ② 部署插件 jar 到网关 | 网关 lib/ 目录 | 运维 | 网关加载插件 |
| ③ 在 iPaaS Portal 注册插件 | 安全管理 > 网关插件 | 管理员 | 插件记录 |
| ④ 配置插件元数据 | 网关插件 > 插件元数据 | 管理员 | 策略配置表单字段 |
| ⑤ 创建 API 策略 | 安全管理 > API 策略 | 管理员 | 策略实例（含配置值） |
| ⑥ 绑定策略应用对象 | 路由 / API / 订阅关系 | 管理员 | 策略关联关系 |
| ⑦ 发布与验证 | 路由发布 + 发请求 | 管理员 | 策略生效 |
# 3. 前置条件
- 已有可访问的 iPaaS Portal 管理端，且具备"安全管理 > 网关插件"和"安全管理 > API 策略"的菜单权限。
- 网关（API Gateway）已安装并能正常启动，
lib/目录可写入。 - 自定义插件的代码已开发完成并通过编译（开发方法见《自定义插件开发指南》）。
⚠️ 最关键的前置约定：插件编码、策略类型名、FilterFactory 类名前缀三者必须一致。例如插件编码填
CustomPolicy，则网关代码中类名必须是CustomPolicyGatewayFilterFactory，@Component("CustomPolicy")的值和getPolicyType()返回值也必须是CustomPolicy。三者不一致是策略无法生效的最常见原因。
# 4. 第一步：开发并部署网关自定义插件
# 4.1 开发插件
完整的开发流程请参考5.19 网关自定义插件开发指南。一个完整的自定义插件包含三部分：
| 组成 | 作用 | 是否必需 |
|---|---|---|
过滤器工厂 XxxGatewayFilterFactory | 真正的过滤逻辑入口 | 必需 |
策略配置 POJO XxxPolicyConfig | 描述策略参数的 Java 对象，对应管理端配置的 JSON | 需要动态配置参数时必需 |
策略缓存类 XxxPolicyConfigCache | 把管理端下发的策略数据缓存到内存供过滤器读取 | 需要动态配置参数时必需 |
开发要点：
- 包名必须以
com.primeton.gateway开头，否则网关不会扫描注册@Component。 - FilterFactory 类名 =
插件编码 + GatewayFilterFactory。 - 策略类型名三处一致：
@Component("X")的值、getPolicyType()返回值、过滤器查询字符串。 - 产物必须是 thin jar，不要打 fat jar，运行期依赖由网关提供。
# 4.2 部署插件
# 把打包好的插件 jar 放进网关 lib 目录
cp my-gateway-plugin-1.0.0.jar API_GATEWAY/lib/
# 重启网关生效（运行中放 jar 不会被加载）
cd API_GATEWAY/bin
./shutdown.sh # Windows 用 shutdown.bat
./startup.sh # Windows 用 startup.bat
验证：在网关
logs/下搜索插件类名，确认 Bean 已被注册。
# 5. 第二步：在管理端注册插件
# 5.1 进入网关插件管理
管理员登录系统，进入管理门户，点击菜单 "安全管理" > "网关插件"，进入网关插件页面。
# 5.2 新增插件
点击"新增"按钮，进入新增插件页面，按以下参数说明填写：
| 参数 | 说明 | 填写要求 |
|---|---|---|
| 插件编码 | 插件唯一不重复标识，网关加载路由通过插件编码定位到插件过滤器。 | 必须与网关代码中 FilterFactory 类名去掉 GatewayFilterFactory 后缀的部分完全一致，也必须等于策略类型名。例如 CustomPolicy。 |
| 插件名称 | 插件名称（中文描述） | 自定义，用于页面展示 |
| 类别 | 插件类型，分为：认证策略、流量控制、数据处理、访问控制、日志策略 | 决定该插件在 API 策略页面归属哪个策略分组 |
| 排序 | 在插件管理页面中的显示顺序 | 数字，越小越靠前 |
| 状态 | 开启 / 关闭 | 开启后在 API 策略管理页面可见可用；关闭则不可见 |
| 是否启用元数据 | 开启 / 关闭 | 开启后才能在操作列使用"插件元数据"管理 |
| 说明 | 插件的功能介绍和使用方式 | 自定义文本 |
填写完成后点击"确定"保存。
📌 插件编码填写示例：假如网关代码里过滤器工厂类名是
CustomPolicyGatewayFilterFactory，策略缓存类注解是@Component("CustomPolicy")，那么这里的"插件编码"必须填CustomPolicy。
# 5.3 插件的其他管理操作
- 编辑：在操作列点击"编辑"可修改插件信息。
- 删除：只有用户新增的插件才可以删除，系统内置插件无法删除。删除插件会同时删除其下所有元数据。
- 批量开启 / 批量关闭：勾选多个插件后批量切换状态。关闭的插件在 API 策略管理页面不显示。
- 查询：支持按插件编码、插件名、状态、类别进行分页查询。
# 6. 第三步：配置插件元数据
插件元数据定义了"基于该插件创建策略时，策略配置表单长什么样"。每一个元数据字段 = 策略配置表单的一个配置项 = 网关过滤器拦截规则的一个参数 = 策略配置 JSON 中的一个 key。
# 6.1 进入插件元数据管理
在"网关插件"管理界面，选择已开启元数据的插件记录，在操作列点击 "插件元数据" 按钮，进入该插件的元数据管理界面。
# 6.2 新增插件元数据
点击"新增"按钮，按以下参数说明填写：
| 参数 | 说明 | 填写要求 |
|---|---|---|
| 插件编码 | 下拉选择元数据所属的插件 | 选择当前插件 |
| 字段 | 字段名称，前端请求实际使用的 key | 每个插件内不能有重复的字段；必须与网关代码中策略配置 POJO（如 CustomPolicyConfig）的字段名一致，也必须与策略配置 JSON 的 key 一致 |
| 数据类型 | 允许输入的数据类型 | 数字 / 字符串 |
| 控件类型 | 输入框的类型 | 输入框 / 密码框 / 选择框 |
| 排序 | 在策略配置页面，字段的显示顺序 | 数字，越小越靠前 |
| 是否必填 | 策略配置页面该字段是否必填 | 是 / 否 |
| 默认值 | 字段默认值 | 可空；新建策略时自动带入 |
| 输入提示 | 字段旁鼠标悬浮提示信息 | 可空 |
| 校验规则 | 字段支持正则表达式规则校验 | 可空；填写合法正则 |
| 描述 | 该字段在配置页面显示的内容 | 即字段的中文名 |
📌 字段填写示例：网关
CustomPolicyConfig有customParam1、customParam2两个字段，那么这里就要新增两条元数据，"字段"分别填customParam1、customParam2，"描述"填对应中文说明。这样创建策略时表单就会显示这两个输入框。
# 6.3 控件类型为"选择框"时
当控件类型选择"选择框"时，下拉框的选项通过元数据的扩展配置（extObj）提供，内容格式示例：
[{"label":"是","value":"true"},{"label":"否","value":"false"}]
# 6.4 元数据的其他管理操作
- 批量删除：勾选多条元数据记录后批量删除。
- 查询：支持按插件编码、插件名称、字段名称分页查询。
- 编辑：在操作列点击"编辑"可修改单条元数据。
# 7. 第四步：创建 API 策略
插件和元数据配置完成后，就可以在 API 策略管理页面创建对应的 API 策略。策略的配置项由插件的元数据控制——元数据定义了哪些字段、字段类型、是否必填等，管理员在创建策略时填写这些字段的具体取值。
# 7.1 进入 API 策略管理
管理员登录系统，进入管理门户，点击菜单 "安全管理" > "API 策略"，进入 API 策略页面，默认展示策略类型页签。
策略类型包含：认证策略、流量控制、数据处理、访问控制、日志策略。API 策略的应用对象为 API、路由、订阅关系。
自定义插件只要状态为"开启"，就会出现在对应类别下的策略类型树中。如果没看到你的插件，请回到"网关插件"页面确认：① 状态已开启；② 类别选择正确。
# 7.2 新建策略
在策略类型树中，找到你的自定义插件所属的策略类型节点。
点击"新建策略"（或对应入口），打开策略配置表单。
表单字段由该插件的元数据动态生成，按字段说明填写策略配置值。
- 必填字段必须填写（元数据中"是否必填"为"是"的字段）。
- 字段会按元数据的"排序"值顺序展示。
- 输入提示、默认值、校验规则都来自元数据配置。
- 选择框类型的字段，下拉选项来自元数据的扩展配置。
填写策略名称（同一系统下策略名称不能重复）。
选择所属系统。
点击"保存"。
# 7.3 策略配置数据说明
保存策略时，表单填写的值会被序列化为一段 JSON 存储到策略的 policyConfig 字段中。例如：
{ "customParam1": "hello", "customParam2": "world" }
这段 JSON 的 key 就是插件元数据的"字段"，也对应网关代码中策略配置 POJO 的属性名。网关收到策略后，会回调插件的 XxxPolicyConfigCache#addPolicyConfig，把 JSON 反序列化为 POJO 存入缓存，供过滤器运行时读取。
💡 因此，元数据的字段名、策略 JSON 的 key、网关 POJO 的属性名，三者必须一致，否则网关反序列化时取不到值。
# 7.4 策略的编辑与删除
- 编辑：在策略列表操作列点击"编辑"，修改配置后保存。修改后会自动同步刷新网关侧的策略缓存。
- 删除：在策略列表操作列点击"删除"。删除策略前会自动解绑其所有应用对象关联，并同步通知网关清除对应策略缓存，同时触发受影响路由的重新发布。
# 8. 第五步：绑定策略应用对象
策略创建后，需要绑定到具体的路由 / API / 订阅关系才会生效。
# 8.1 应用对象粒度
API 策略支持三种粒度的应用对象：
| 粒度 | effectLevel | 说明 |
|---|---|---|
| 路由 | 1 | 对某条路由下所有接口生效（仅发布到 Gateway Server 的接口可配置路由策略） |
| API | 2 | 对某个具体接口生效 |
| 订阅关系 | 3 | 对"某个消费方 + 某个接口"的组合生效 |
# 8.2 策略添加应用对象的限制
- 认证策略：一个 API 只能被认证策略下的某一种认证策略类型的一个策略关联。例如 test 接口被 Basic 认证策略的策略 A 关联，则无法再被 Basic 认证策略的策略 B 关联，也无法被 Token 认证策略的策略 1 关联。路由、订阅关系和 API 的限制一致。
- 其他策略：一个 API 只能被一种策略类型的一个策略关联。例如 test 接口被流量控制策略的策略 A 关联，则无法再被流量控制策略的策略 B 关联，但还可以被请求体限流策略的策略 1 关联。路由、订阅关系和 API 的限制一致。
# 8.3 绑定方式
在策略详情页或应用对象管理页，将策略关联到目标路由 / API / 订阅关系。保存关联后：
- 系统会自动同步策略关系到网关侧。
- 系统会自动触发受影响路由的重新发布，使策略在网关生效。
- 重复关联同一对象会被拦截并提示"不能重复选择该策略"。
# 8.4 策略的优先级
策略的控制优先级是 "订阅关系 > API > 路由"。
以 Basic 认证策略为例，新建三个 Basic 认证策略（策略 A、策略 B、策略 C），有一个已发布接口（test 接口），test 接口被 consumer1 和 consumer2 两个系统订阅：
- 策略 A 的订阅关系应用对象添加 test 接口 - consumer1 订阅关系
- 策略 B 的 API 应用对象添加 test 接口
- 策略 C 的路由应用对象添加 test 接口的所属路由
调用 test 接口时：
- 如果消费方是 consumer1 → 策略 A 生效
- 其他消费方调用 test 接口 → 策略 B 生效
- 如果策略 B 的 API 应用对象删除了 test 接口 → 其他消费方调用时 策略 C 生效
# 9. 第六步：发布与验证
# 9.1 确保路由已发布
策略绑定到路由/API/订阅关系后，需确保对应路由已发布到网关。新建或修改策略关联时系统会自动触发受影响路由的重新发布。
# 9.2 验证策略已生效
方式一：查看网关日志。
发起一次请求，在网关 logs/ 下查看过滤器是否打印了执行日志（如示例中的 custom filter execute），以及策略参数是否被正确读取。
方式二：发请求实测。
向绑定了策略的接口发起请求，观察：
- 过滤器是否被执行（日志确认）。
- 策略参数值是否正确（日志中打印的参数值应与策略配置一致）。
- 拦截效果是否符合预期（如拒绝、放行、改写等）。
方式三：策略缓存匹配优先级。
网关侧策略缓存的匹配优先级为：ClientId+OperationCode > OperationCode > RouteId。即订阅关系级别策略 > API 级别策略 > 路由级别策略 > 系统级别策略，与管理端的优先级规则一致。
# 10. 策略的生效与热更新机制
| 操作 | 网关侧行为 |
|---|---|
| 新建策略 | 策略数据写入 iPaaS Portal 数据库；绑定应用对象后才下发到网关 |
| 修改策略 | 自动同步刷新网关侧策略缓存 |
| 删除策略 | 自动解绑所有应用对象关联，同步通知网关清除策略缓存，并重发布受影响路由 |
| 新增策略关联 | 系统级/API级/订阅关系级会触发受影响路由重发布 |
| 删除策略关联 | 同步清除网关侧对应策略缓存，并重发布受影响路由 |
# 11. 常见问题与排错
# Q1：API 策略管理页面看不到我的自定义插件
排查：
- 回到"网关插件"页面，确认插件状态为"开启"。关闭状态的插件在 API 策略页面不显示。
- 确认插件的类别选择正确，策略类型树按类别分组展示。
- 自定义插件不支持ESB Server，如果接口发布到 ESB Server（而非 Gateway Server），则该插件不会出现在该接口的策略配置中。
# Q2：策略配置表单字段不正确或缺失
排查：
- 确认插件**"是否启用元数据"为开启**状态。
- 进入"插件元数据"管理，确认对应字段已新增且"字段"名正确。
- 元数据的"字段"名必须与网关代码中策略配置 POJO 的属性名完全一致（区分大小写）。
# Q3：策略已创建并绑定，但网关过滤器读不到策略参数（返回 null）
排查：
- 确认插件编码、策略类型名、FilterFactory 类名前缀三者完全一致。
- 插件编码 =
CustomPolicy - 网关类名 =
CustomPolicyGatewayFilterFactory @Component("CustomPolicy")的值 =CustomPolicygetPolicyType()返回值 =CustomPolicy- 过滤器中
PolicyConfigCacheUtil.getPolicyConfig(exchange, "CustomPolicy", ...)的字符串 =CustomPolicy
- 插件编码 =
- 确认策略已绑定到当前请求命中的路由/API/订阅关系。
- 确认网关已重启加载了插件 jar（运行中放 jar 不生效）。
- 确认策略缓存类的包名以
com.primeton.gateway开头（否则不被扫描注册）。
# Q4：策略配置 JSON 的 key 与网关 POJO 字段对不上
原因： 元数据的"字段"名与网关策略配置 POJO 的属性名不一致，导致网关反序列化时取不到值。
解决： 修改元数据的"字段"名，使其与 POJO 属性名完全一致；或修改 POJO 属性名使其与元数据一致。两者改完后，已创建的策略需要重新编辑保存以重新生成 JSON。
# Q5：插件 jar 已放进 lib/ 但过滤器完全不生效
排查：
- 确认已重启网关（
lib/目录在 JVM 启动那一刻固定，运行中新增 jar 不会被加载）。 - 确认所有类的包名以
com.primeton.gateway开头（网关只扫描该包及其子包）。 - 确认插件 jar 是 thin jar（不含
BOOT-INF/、不含 spring/reactor 等第三方包），fat jar 会导致类加载失败。 - 确认路由的
filters已加上过滤器名（去掉GatewayFilterFactory后缀的部分）。
# Q6：Windows 下替换插件 jar 报"文件被占用"
原因： JVM 运行期间持有 jar 文件句柄。
解决： 先停止网关，再替换 jar，再启动。
# Q7：删除策略后接口报错或策略仍残留
排查： 删除策略时系统会自动解绑关联并通知网关清除缓存、重发布受影响路由。如果网关侧未及时刷新，可手动重发布对应路由。
# 12. 完整链路校验清单
在完成自定义策略的全流程配置后，请逐条确认：
| 检查项 | 期望 |
|---|---|
网关插件 jar 已放入 lib/ 并重启网关 | 是 |
| 插件所有类的包名 | 以 com.primeton.gateway 开头 |
| 插件 jar 为 thin jar | 是（不含 BOOT-INF、不含第三方包） |
| FilterFactory 类名 | 插件编码 + GatewayFilterFactory |
@Component("X") 的值 / getPolicyType() 返回值 / 过滤器查询字符串 | 三者完全一致，且等于插件编码 |
| iPaaS Portal 中插件记录的插件编码 | 与上述策略类型名一致 |
| 插件状态 | 开启 |
| 插件"是否启用元数据" | 开启 |
| 元数据的"字段"名 | 与网关 POJO 属性名、策略 JSON key 一致 |
| 策略已创建并填写配置值 | 是 |
| 策略已绑定到路由/API/订阅关系 | 是 |
| 路由已发布到网关 | 是 |
| 发请求验证过滤器执行且参数正确 | 是 |
至此，你已经掌握了从开发网关自定义插件、注册插件元数据、创建 API 策略、到绑定应用对象并验证生效的完整操作流程。