✨ [2025-05-07] 添加基础工具使用指南
All checks were successful
Publish to Confluence / confluence (push) Successful in 1m21s
All checks were successful
Publish to Confluence / confluence (push) Successful in 1m21s
This commit is contained in:
parent
3bfea7cda3
commit
a75d36872a
91
文档/基础组件/20250509-EngineStarterFeign使用指南.md
Normal file
91
文档/基础组件/20250509-EngineStarterFeign使用指南.md
Normal file
@ -0,0 +1,91 @@
|
||||
<!-- Space: qifu -->
|
||||
<!-- Parent: 后端技术&知识&规范 -->
|
||||
<!-- Parent: 技术方案 -->
|
||||
<!-- Parent: 基建 -->
|
||||
<!-- Parent: 00-基础组件 -->
|
||||
<!-- Title: 20250509-EngineStarterFeign使用指南 -->
|
||||
|
||||
<!-- Macro: :anchor\((.*)\):
|
||||
Template: ac:anchor
|
||||
Anchor: ${1} -->
|
||||
<!-- Macro: \!\[.*\]\((.+)\)\<\!\-\- width=(.*) \-\-\>
|
||||
Template: ac:image
|
||||
Url: ${1}
|
||||
Width: ${2} -->
|
||||
<!-- Macro: \<\!\-\- :toc: \-\-\>
|
||||
Template: ac:toc
|
||||
Printable: 'false'
|
||||
MinLevel: 2
|
||||
MaxLevel: 4 -->
|
||||
<!-- Include: 杂项/声明文件.md -->
|
||||
|
||||
<!-- :toc: -->
|
||||
|
||||
# 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
|
||||
|
||||
<dependency>
|
||||
<groupId>com.yuanmeng.engine</groupId>
|
||||
<artifactId>engine-starter-feign</artifactId>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
------
|
||||
|
||||
## 完整默认配置文件
|
||||
|
||||
```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
|
||||
```
|
||||
262
文档/基础组件/20250509-EngineStarterWeb使用指南.md
Normal file
262
文档/基础组件/20250509-EngineStarterWeb使用指南.md
Normal file
@ -0,0 +1,262 @@
|
||||
<!-- Space: qifu -->
|
||||
<!-- Parent: 后端技术&知识&规范 -->
|
||||
<!-- Parent: 技术方案 -->
|
||||
<!-- Parent: 基建 -->
|
||||
<!-- Parent: 00-基础组件 -->
|
||||
<!-- Title: 20250509-EngineStarterWeb使用指南 -->
|
||||
|
||||
<!-- Macro: :anchor\((.*)\):
|
||||
Template: ac:anchor
|
||||
Anchor: ${1} -->
|
||||
<!-- Macro: \!\[.*\]\((.+)\)\<\!\-\- width=(.*) \-\-\>
|
||||
Template: ac:image
|
||||
Url: ${1}
|
||||
Width: ${2} -->
|
||||
<!-- Macro: \<\!\-\- :toc: \-\-\>
|
||||
Template: ac:toc
|
||||
Printable: 'false'
|
||||
MinLevel: 2
|
||||
MaxLevel: 4 -->
|
||||
<!-- Include: 杂项/声明文件.md -->
|
||||
|
||||
<!-- :toc: -->
|
||||
|
||||
# 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
|
||||
|
||||
<dependency>
|
||||
<groupId>com.yuanmeng.engine</groupId>
|
||||
<artifactId>engine-starter-web</artifactId>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
### 使用工具
|
||||
|
||||
#### 忽略结果封装
|
||||
|
||||
```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<String> {
|
||||
|
||||
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> string = (Collection<String>) ids;
|
||||
Map<String, String> 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<TestData> autofill() {
|
||||
List<TestData> 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<TestDataSecond> autofillSecond() {
|
||||
List<TestDataSecond> 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"
|
||||
```
|
||||
Loading…
x
Reference in New Issue
Block a user