From a75d36872a9359d51a361bf0b74d192b684cfccf Mon Sep 17 00:00:00 2001 From: liuxiaohua Date: Fri, 9 May 2025 17:02:39 +0800 Subject: [PATCH] =?UTF-8?q?=E2=9C=A8=20[2025-05-07]=20=E6=B7=BB=E5=8A=A0?= =?UTF-8?q?=E5=9F=BA=E7=A1=80=E5=B7=A5=E5=85=B7=E4=BD=BF=E7=94=A8=E6=8C=87?= =?UTF-8?q?=E5=8D=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../20250509-EngineStarterFeign使用指南.md | 91 ++++++ .../20250509-EngineStarterWeb使用指南.md | 262 ++++++++++++++++++ 2 files changed, 353 insertions(+) create mode 100644 文档/基础组件/20250509-EngineStarterFeign使用指南.md create mode 100644 文档/基础组件/20250509-EngineStarterWeb使用指南.md diff --git a/文档/基础组件/20250509-EngineStarterFeign使用指南.md b/文档/基础组件/20250509-EngineStarterFeign使用指南.md new file mode 100644 index 0000000..0d32b4b --- /dev/null +++ b/文档/基础组件/20250509-EngineStarterFeign使用指南.md @@ -0,0 +1,91 @@ + + + + + + + + + + + + + + +# engine-starter-feign 使用教程 + +> 基于 Feign 的通用封装 +> 具体使用可参考 [engine-sample > engine-sample-starter-web](../engine-sample/engine-sample-starter-web) +> 版本要求：`$verison >= 1.1.0-SNAPSHOT` + +## 功能特性 + +- [X] 请求头添加内部请求标识 `X-QiFu-From-In: true` +- [X] 请求头透传 +- [X] 请求结果解析映射（解封装 `Result`） + +------- + +## 快速使用 + +- **注意：** `qifu-saas-parent` 版本需要高于 `1.1.0-SNAPSHOT` +- **注意：** 启动类 `@ComponentScan` 需要变更为如下形式 +- ```java + @ComponentScan(value = "com.yuanmeng.*", + excludeFilters = { + @ComponentScan.Filter(type = FilterType.CUSTOM, classes = TypeExcludeFilter.class), + @ComponentScan.Filter(type = FilterType.CUSTOM, classes = AutoConfigurationExcludeFilter.class) + }) + @SpringBootApplication + public class SampleStarterWebApplication { + + public static void main(String[] args) { + SpringApplication.run(SampleStarterWebApplication.class, args); + } + + } + ``` + +### 添加依赖 + +```xml + + + com.yuanmeng.engine + engine-starter-feign + +``` + +------ + +## 完整默认配置文件 + +```yaml +yuanmeng: + feign: + #- 开启feign自动配置 + enable: true + #- 开启请求头内部标识 + enable-contract: true + #- 开启旧包兼容 + enable-ignore: true + #- 开启结果解析 + enable-decoder: true + #- 开启请求头传递 + enable-interceptor: true + #- 链接超时时间 + connect-timeout: 10 + connect-time-unit: seconds + #- 读取超时时间 + read-timeout: 60 + read-time-unit: seconds +``` \ No newline at end of file diff --git a/文档/基础组件/20250509-EngineStarterWeb使用指南.md b/文档/基础组件/20250509-EngineStarterWeb使用指南.md new file mode 100644 index 0000000..eedef3c --- /dev/null +++ b/文档/基础组件/20250509-EngineStarterWeb使用指南.md @@ -0,0 +1,262 @@ + + + + + + + + + + + + + + +# engine-starter-web 使用教程 + +> 基于 web 的各种工具封装 +> 具体使用可参考 [engine-sample > engine-sample-starter-web](../engine-sample/engine-sample-starter-web) +> 版本要求：`$verison >= 1.1.0-SNAPSHOT` +> 去除 security 相关配置 + +## 功能特性 + +- [X] `@YmAutoFill` 和 `@YmAutoFillResp`: 结果自动填充 +- [X] `@YmIgnoreResultWrapper`: 忽略 `Result` 结果包装 +- [X] `YmResponseAdvice`: 全局结果封装 +- [X] `YmGlobalExceptionHandlerAdvice`: 全局异常拦截处理 +- [X] `YmAutofillResponseAdvice`: 全局返回结果填充处理 +- [X] `YmHealthCheckFilter`: 全局健康检查接口 +- [X] `YmRequestBodyWrapperFilter`: request 和 response 可重复读封装 +- [X] `YmRequestPrintFilter`: 请求日志打印 +- [X] `YmThreadLocalFilter`: 登录用户信息解析存储（后续会迁移到网关，需要兼容） +- [X] `YmUserLoginFilter`: 用户登录校验（后续会迁移到网关，默认关闭） +- [X] `YmSecurityUtils`: 登录用户信息获取 + +------- + +## 快速使用 + +- **注意：** `qifu-saas-parent` 版本需要高于 `1.1.0-SNAPSHOT` +- **注意：** `pom.xml` 中 `engine-starter-web` 依赖要置于 `web-core` 和 `oauth2-core` 之前 +- **注意：** 启动类 `@ComponentScan` 需要变更为如下形式 +- ```java + @ComponentScan(value = "com.yuanmeng.*", + excludeFilters = { + @ComponentScan.Filter(type = FilterType.CUSTOM, classes = TypeExcludeFilter.class), + @ComponentScan.Filter(type = FilterType.CUSTOM, classes = AutoConfigurationExcludeFilter.class) + }) + @SpringBootApplication + public class SampleStarterWebApplication { + + public static void main(String[] args) { + SpringApplication.run(SampleStarterWebApplication.class, args); + } + + } + ``` +- **注意：** 引入 `engine-starter-web` 后可以移除 `web-core` 和 `oauth2-core` 依赖。但是 `SecurityUtils` 需要改为 + `YmSecurityUtils` + +### 添加依赖 + +```xml + + + com.yuanmeng.engine + engine-starter-web + +``` + +### 使用工具 + +#### 忽略结果封装 + +```java +public class Usage { + + /** + * 测试忽略包装 + * + * @return 结果 + */ + @YmIgnoreResultWrapper + @GetMapping("/ignore-result-wrapper") + public String ignoreResultWrapper() { + return "ignore-result-wrapper success"; + } + +} +``` + +#### 全局异常拦截 + +```java +public class Usage { + + @GetMapping("/exception") + public String exception() { + throw new RuntimeException("exception"); + } + + @GetMapping("/ym-exception") + public String ymException() { + throw new YmException("ym exception"); + } + + @GetMapping("/ym-biz-exception") + public String ymBizException() { + throw new YmBizException(YmResultCode.BASE_ERROR); + } + + @GetMapping("/ym-biz-data-exception") + public String ymBizDataException() { + throw new YmBizDataException(YmResultCode.BASE_ERROR, + new TestData(TestStatusEnum.SUCCESS.getCode(), "1")); + } + + @YmAutofillResp + @GetMapping("/ym-biz-data-exception-fill") + public String ymBizDataExceptionFill() { + throw new YmBizDataException(YmResultCode.BASE_ERROR, + new TestData(TestStatusEnum.SUCCESS.getCode(), "1")); + } + +} +``` + +#### 结果自动填充 + +```java + +@Getter +@AllArgsConstructor +public enum TestStatusEnum implements YmBaseEnum { + + SUCCESS("SUCCESS", "成功"), + FAIL("FAIL", "失败"), + ; + + private final String code; + private final String desc; + +} + +@Component +public class TestAutoFillHandler implements YmAutofillHandler { + + @Override + public Map handle(Collection ids, YmAutofillInfo autofill) { + Collection string = (Collection) ids; + Map result = new HashMap<>(); + string.forEach(k -> result.put(k, k + "value")); + return result; + } + +} + +@Data +@NoArgsConstructor +public class TestData { + + @YmAutofill(enumCls = TestStatusEnum.class) + private String statusName; + private String status; + + private String code; + @YmAutofill(from = "code", type = YmAutofillType.BEAN, handler = TestAutoFillHandler.class) + private String msg; + + public TestData(String status, String code) { + this.status = status; + this.code = code; + } + +} + +@Data +@NoArgsConstructor +public class TestDataSecond { + + private String statusName; + private String status; + + private String code; + private String msg; + + public TestDataSecond(String status, String code) { + this.status = status; + this.code = code; + } + +} + + +public class Usage { + + @YmAutofillResp + @GetMapping("/autofill") + public List autofill() { + List list = new ArrayList<>(); + list.add(new TestData(TestStatusEnum.SUCCESS.getCode(), "1")); + list.add(new TestData(TestStatusEnum.FAIL.getCode(), "2")); + return list; + } + + @YmAutofillResp({ + @YmAutofill(from = "status", target = "statusName", enumCls = TestStatusEnum.class), + @YmAutofill(from = "code", target = "msg", type = YmAutofillType.BEAN, handler = TestAutoFillHandler.class) + }) + @GetMapping("/autofill-second") + public List autofillSecond() { + List list = new ArrayList<>(); + list.add(new TestDataSecond(TestStatusEnum.SUCCESS.getCode(), "1")); + list.add(new TestDataSecond(TestStatusEnum.FAIL.getCode(), "2")); + return list; + } + +} +``` + +------ + +## 完整默认配置文件 + +```yaml +yuanmeng: + web: + #- 开启starter + enable: true + enable-ignore: true + enable-audit-handler: true + enable-result-wrapper: true + enable-exception-handler: true + filter: + enable-health-check: true + enable-thread-local: true + enable-user-login: false + skip-path: + - "/test" + request-body: + enable: true + filter-uris: + - "/test1" + track: + enable: true + filter-uris: + - "/test2" + sensitive-keys: + - "password" + print-type: 2 + external-url-list: + - "/external/test" +``` \ No newline at end of file