491 lines
30 KiB
Markdown
491 lines
30 KiB
Markdown
# 通用API规范
|
||
|
||
<cite>
|
||
**本文引用的文件**
|
||
- [CommonResult.java](file://viewsh-framework/viewsh-common/src/main/java/com/viewsh/framework/common/pojo/CommonResult.java)
|
||
- [PageParam.java](file://viewsh-framework/viewsh-common/src/main/java/com/viewsh/framework/common/pojo/PageParam.java)
|
||
- [SortablePageParam.java](file://viewsh-framework/viewsh-common/src/main/java/com/viewsh/framework/common/pojo/SortablePageParam.java)
|
||
- [SortingField.java](file://viewsh-framework/viewsh-common/src/main/java/com/viewsh/framework/common/pojo/SortingField.java)
|
||
- [GlobalErrorCodeConstants.java](file://viewsh-framework/viewsh-common/src/main/java/com/viewsh/framework/common/exception/enums/GlobalErrorCodeConstants.java)
|
||
- [RpcConstants.java](file://viewsh-framework/viewsh-common/src/main/java/com/viewsh/framework/common/enums/RpcConstants.java)
|
||
- [WebProperties.java](file://viewsh-framework/viewsh-spring-boot-starter-web/src/main/java/com/viewsh/framework/web/config/WebProperties.java)
|
||
- [WebFrameworkUtils.java](file://viewsh-framework/viewsh-spring-boot-starter-web/src/main/java/com/viewsh/framework/web/core/util/WebFrameworkUtils.java)
|
||
- [ApiConstants.java（系统模块）](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/enums/ApiConstants.java)
|
||
- [ApiConstants.java（ops模块）](file://viewsh-module-ops/viewsh-module-ops-api/src/main/java/com/viewsh/module/ops/enums/ApiConstants.java)
|
||
- [ApiAccessLog.java](file://viewsh-framework/viewsh-spring-boot-starter-web/src/main/java/com/viewsh/framework/apilog/core/annotation/APIAccessLog.java)
|
||
- [ApiAccessLogFilter.java](file://viewsh-framework/viewsh-spring-boot-starter-web/src/main/java/com/viewsh/framework/apilog/core/filter/APIAccessLogFilter.java)
|
||
- [Idempotent.java](file://viewsh-framework/viewsh-spring-boot-starter-protection/src/main/java/com/viewsh/framework/idempotent/core/annotation/Idempotent.java)
|
||
- [IdempotentAspect.java](file://viewsh-framework/viewsh-spring-boot-starter-protection/src/main/java/com/viewsh/framework/idempotent/core/aop/IdempotentAspect.java)
|
||
- [RateLimiter.java](file://viewsh-framework/viewsh-spring-boot-starter-protection/src/main/java/com/viewsh/framework/ratelimiter/core/annotation/RateLimiter.java)
|
||
- [RateLimiterAspect.java](file://viewsh-framework/viewsh-spring-boot-starter-protection/src/main/java/com/viewsh/framework/ratelimiter/core/aop/RateLimiterAspect.java)
|
||
- [RateLimiterRedisDAO.java](file://viewsh-framework/viewsh-spring-boot-starter-protection/src/main/java/com/viewsh/framework/ratelimiter/core/redis/RateLimiterRedisDAO.java)
|
||
- [ApiSignature.java](file://viewsh-framework/viewsh-spring-boot-starter-protection/src/main/java/com/viewsh/framework/signature/core/annotation/ApiSignature.java)
|
||
- [ApiSignatureAspect.java](file://viewsh-framework/viewsh-spring-boot-starter-protection/src/main/java/com/viewsh/framework/signature/core/aop/ApiSignatureAspect.java)
|
||
- [OAuth2TokenServiceImpl.java](file://viewsh-module-system/viewsh-module-system-server/src/main/java/com/viewsh/module/system/service/oauth2/OAuth2TokenServiceImpl.java)
|
||
- [OAuth2AccessTokenRedisDAO.java](file://viewsh-module-system/viewsh-module-system-server/src/main/java/com/viewsh/module/system/dal/redis/oauth2/OAuth2AccessTokenRedisDAO.java)
|
||
- [OAuth2OpenControllerTest.java](file://viewsh-module-system/viewsh-module-system-server/src/test/java/com/viewsh/module/system/controller/admin/oauth2/OAuth2OpenControllerTest.java)
|
||
- [Knife4jOpenApiCustomizer.java](file://viewsh-framework/viewsh-spring-boot-starter-web/src/main/java/com/viewsh/framework/swagger/config/Knife4jOpenApiCustomizer.java)
|
||
- [接口文档.md](file://docs/technical-overview/07-接口文档.md)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [引言](#引言)
|
||
2. [项目结构](#项目结构)
|
||
3. [核心组件](#核心组件)
|
||
4. [架构总览](#架构总览)
|
||
5. [详细组件分析](#详细组件分析)
|
||
6. [依赖关系分析](#依赖关系分析)
|
||
7. [性能考量](#性能考量)
|
||
8. [故障排查指南](#故障排查指南)
|
||
9. [结论](#结论)
|
||
10. [附录](#附录)
|
||
|
||
## 引言
|
||
本文件旨在为整个平台制定统一的API规范，覆盖响应格式、错误码、分页与排序、版本管理与兼容性、认证授权、限流与幂等、API文档生成与维护、测试与调试、以及安全防护等方面。规范以仓库现有实现为依据，确保跨模块一致性与可维护性。
|
||
|
||
## 项目结构
|
||
平台采用多模块架构，API规范涉及以下关键层次：
|
||
- 通用响应与异常：统一返回体、错误码、分页与排序模型
|
||
- 网关与路由：前缀与路由规则、RPC与HTTP区分
|
||
- 认证授权：OAuth2令牌生命周期与Redis存储
|
||
- 安全与防护：签名、限流、幂等
|
||
- 文档生成：Knife4j聚合与标签排序
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "通用层"
|
||
CR["CommonResult<br/>统一响应"]
|
||
EC["GlobalErrorCodeConstants<br/>全局错误码"]
|
||
PP["PageParam/SortablePageParam<br/>分页与排序"]
|
||
end
|
||
subgraph "网关与路由"
|
||
WP["WebProperties<br/>前缀配置"]
|
||
WFU["WebFrameworkUtils<br/>请求上下文/头解析"]
|
||
RC["RpcConstants<br/>RPC前缀"]
|
||
end
|
||
subgraph "认证授权"
|
||
OAT["OAuth2TokenServiceImpl<br/>令牌创建/刷新"]
|
||
OAR["OAuth2AccessTokenRedisDAO<br/>令牌Redis存储"]
|
||
end
|
||
subgraph "安全与防护"
|
||
SIG["ApiSignatureAspect<br/>请求签名"]
|
||
RL["RateLimiterAspect/DAO<br/>限流"]
|
||
IDP["IdempotentAspect<br/>幂等"]
|
||
end
|
||
subgraph "文档"
|
||
K4J["Knife4jOpenApiCustomizer<br/>文档聚合/排序"]
|
||
end
|
||
CR --> EC
|
||
PP --> CR
|
||
WP --> WFU
|
||
RC --> WP
|
||
OAT --> OAR
|
||
SIG --> CR
|
||
RL --> CR
|
||
IDP --> CR
|
||
K4J --> CR
|
||
```
|
||
|
||
**图表来源**
|
||
- [CommonResult.java](file://viewsh-framework/viewsh-common/src/main/java/com/viewsh/framework/common/pojo/CommonResult.java#L1-L122)
|
||
- [GlobalErrorCodeConstants.java](file://viewsh-framework/viewsh-common/src/main/java/com/viewsh/framework/common/exception/enums/GlobalErrorCodeConstants.java#L1-L42)
|
||
- [PageParam.java](file://viewsh-framework/viewsh-common/src/main/java/com/viewsh/framework/common/pojo/PageParam.java#L1-L37)
|
||
- [SortablePageParam.java](file://viewsh-framework/viewsh-common/src/main/java/com/viewsh/framework/common/pojo/SortablePageParam.java#L1-L19)
|
||
- [WebProperties.java](file://viewsh-framework/viewsh-spring-boot-starter-web/src/main/java/com/viewsh/framework/web/config/WebProperties.java#L1-L67)
|
||
- [WebFrameworkUtils.java](file://viewsh-framework/viewsh-spring-boot-starter-web/src/main/java/com/viewsh/framework/web/core/util/WebFrameworkUtils.java#L1-L184)
|
||
- [RpcConstants.java](file://viewsh-framework/viewsh-common/src/main/java/com/viewsh/framework/common/enums/RpcConstants.java#L1-L41)
|
||
- [OAuth2TokenServiceImpl.java](file://viewsh-module-system/viewsh-module-system-server/src/main/java/com/viewsh/module/system/service/oauth2/OAuth2TokenServiceImpl.java#L62-L86)
|
||
- [OAuth2AccessTokenRedisDAO.java](file://viewsh-module-system/viewsh-module-system-server/src/main/java/com/viewsh/module/system/dal/redis/oauth2/OAuth2AccessTokenRedisDAO.java#L1-L37)
|
||
- [ApiSignatureAspect.java](file://viewsh-framework/viewsh-spring-boot-starter-protection/src/main/java/com/viewsh/framework/signature/core/aop/ApiSignatureAspect.java#L1-L40)
|
||
- [RateLimiterAspect.java](file://viewsh-framework/viewsh-spring-boot-starter-protection/src/main/java/com/viewsh/framework/ratelimiter/core/aop/RateLimiterAspect.java#L1-L36)
|
||
- [RateLimiterRedisDAO.java](file://viewsh-framework/viewsh-spring-boot-starter-protection/src/main/java/com/viewsh/framework/ratelimiter/core/redis/RateLimiterRedisDAO.java#L1-L66)
|
||
- [IdempotentAspect.java](file://viewsh-framework/viewsh-spring-boot-starter-protection/src/main/java/com/viewsh/framework/idempotent/core/aop/IdempotentAspect.java#L1-L38)
|
||
- [Knife4jOpenApiCustomizer.java](file://viewsh-framework/viewsh-spring-boot-starter-web/src/main/java/com/viewsh/framework/swagger/config/Knife4jOpenApiCustomizer.java#L56-L113)
|
||
|
||
**章节来源**
|
||
- [接口文档.md](file://docs/technical-overview/07-接口文档.md#L1-L106)
|
||
|
||
## 核心组件
|
||
- 统一响应体：所有HTTP接口返回统一结构，包含业务状态码、提示信息与数据载体
|
||
- 错误码体系：区分HTTP状态与业务错误码，覆盖客户端、服务端与自定义错误
|
||
- 分页与排序：标准化分页参数与排序字段，支持多字段排序
|
||
- 版本前缀与路由：RESTful URL按模块前缀划分，RPC接口走独立前缀
|
||
- 认证授权：OAuth2令牌创建与刷新，Redis存储访问令牌
|
||
- 安全与防护：签名验证、限流、幂等拦截
|
||
- 文档生成：Knife4j聚合与标签排序增强
|
||
|
||
**章节来源**
|
||
- [CommonResult.java](file://viewsh-framework/viewsh-common/src/main/java/com/viewsh/framework/common/pojo/CommonResult.java#L1-L122)
|
||
- [GlobalErrorCodeConstants.java](file://viewsh-framework/viewsh-common/src/main/java/com/viewsh/framework/common/exception/enums/GlobalErrorCodeConstants.java#L1-L42)
|
||
- [PageParam.java](file://viewsh-framework/viewsh-common/src/main/java/com/viewsh/framework/common/pojo/PageParam.java#L1-L37)
|
||
- [SortablePageParam.java](file://viewsh-framework/viewsh-common/src/main/java/com/viewsh/framework/common/pojo/SortablePageParam.java#L1-L19)
|
||
- [SortingField.java](file://viewsh-framework/viewsh-common/src/main/java/com/viewsh/framework/common/pojo/SortingField.java#L1-L38)
|
||
- [WebProperties.java](file://viewsh-framework/viewsh-spring-boot-starter-web/src/main/java/com/viewsh/framework/web/config/WebProperties.java#L1-L67)
|
||
- [RpcConstants.java](file://viewsh-framework/viewsh-common/src/main/java/com/viewsh/framework/common/enums/RpcConstants.java#L1-L41)
|
||
- [OAuth2TokenServiceImpl.java](file://viewsh-module-system/viewsh-module-system-server/src/main/java/com/viewsh/module/system/service/oauth2/OAuth2TokenServiceImpl.java#L62-L86)
|
||
- [OAuth2AccessTokenRedisDAO.java](file://viewsh-module-system/viewsh-module-system-server/src/main/java/com/viewsh/module/system/dal/redis/oauth2/OAuth2AccessTokenRedisDAO.java#L1-L37)
|
||
- [ApiSignatureAspect.java](file://viewsh-framework/viewsh-spring-boot-starter-protection/src/main/java/com/viewsh/framework/signature/core/aop/ApiSignatureAspect.java#L1-L40)
|
||
- [RateLimiterAspect.java](file://viewsh-framework/viewsh-spring-boot-starter-protection/src/main/java/com/viewsh/framework/ratelimiter/core/aop/RateLimiterAspect.java#L1-L36)
|
||
- [RateLimiterRedisDAO.java](file://viewsh-framework/viewsh-spring-boot-starter-protection/src/main/java/com/viewsh/framework/ratelimiter/core/redis/RateLimiterRedisDAO.java#L1-L66)
|
||
- [IdempotentAspect.java](file://viewsh-framework/viewsh-spring-boot-starter-protection/src/main/java/com/viewsh/framework/idempotent/core/aop/IdempotentAspect.java#L1-L38)
|
||
- [Knife4jOpenApiCustomizer.java](file://viewsh-framework/viewsh-spring-boot-starter-web/src/main/java/com/viewsh/framework/swagger/config/Knife4jOpenApiCustomizer.java#L56-L113)
|
||
|
||
## 架构总览
|
||
平台API遵循RESTful风格，HTTP状态码用于网络层，业务状态码用于业务层；通过前缀区分Admin与App接口，RPC接口走独立前缀；认证采用OAuth2，安全通过签名、限流与幂等保障；文档通过Knife4j聚合。
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant C as "客户端"
|
||
participant G as "网关/Gateway"
|
||
participant S as "业务服务"
|
||
participant SEC as "安全组件"
|
||
participant DOC as "文档聚合"
|
||
C->>G : "HTTP 请求 (含前缀)"
|
||
G->>S : "路由转发"
|
||
S->>SEC : "鉴权/签名/限流/幂等"
|
||
SEC-->>S : "通过/拒绝"
|
||
S-->>C : "统一响应体 (code/msg/data)"
|
||
DOC-->>C : "Knife4j 聚合文档"
|
||
```
|
||
|
||
**图表来源**
|
||
- [WebProperties.java](file://viewsh-framework/viewsh-spring-boot-starter-web/src/main/java/com/viewsh/framework/web/config/WebProperties.java#L19-L22)
|
||
- [RpcConstants.java](file://viewsh-framework/viewsh-common/src/main/java/com/viewsh/framework/common/enums/RpcConstants.java#L14-L27)
|
||
- [CommonResult.java](file://viewsh-framework/viewsh-common/src/main/java/com/viewsh/framework/common/pojo/CommonResult.java#L20-L37)
|
||
- [Knife4jOpenApiCustomizer.java](file://viewsh-framework/viewsh-spring-boot-starter-web/src/main/java/com/viewsh/framework/swagger/config/Knife4jOpenApiCustomizer.java#L56-L113)
|
||
|
||
**章节来源**
|
||
- [接口文档.md](file://docs/technical-overview/07-接口文档.md#L5-L73)
|
||
|
||
## 详细组件分析
|
||
|
||
### 统一响应与错误码
|
||
- 响应体字段
|
||
- code：业务错误码，0表示成功
|
||
- msg：错误提示信息
|
||
- data：业务数据
|
||
- 错误码范围
|
||
- 客户端错误：400、401、403、404、405、423、429
|
||
- 服务端错误：500、501、502
|
||
- 自定义错误：900、901、999
|
||
- 使用建议
|
||
- 成功返回使用统一成功码
|
||
- 异常抛出时使用全局错误码或业务错误码
|
||
|
||
```mermaid
|
||
classDiagram
|
||
class CommonResult {
|
||
+Integer code
|
||
+String msg
|
||
+T data
|
||
+isSuccess() boolean
|
||
+checkError() void
|
||
}
|
||
class GlobalErrorCodeConstants {
|
||
<<interface>>
|
||
+SUCCESS
|
||
+BAD_REQUEST
|
||
+UNAUTHORIZED
|
||
+FORBIDDEN
|
||
+NOT_FOUND
|
||
+METHOD_NOT_ALLOWED
|
||
+LOCKED
|
||
+TOO_MANY_REQUESTS
|
||
+INTERNAL_SERVER_ERROR
|
||
+NOT_IMPLEMENTED
|
||
+ERROR_CONFIGURATION
|
||
+REPEATED_REQUESTS
|
||
+DEMO_DENY
|
||
+UNKNOWN
|
||
}
|
||
CommonResult --> GlobalErrorCodeConstants : "使用"
|
||
```
|
||
|
||
**图表来源**
|
||
- [CommonResult.java](file://viewsh-framework/viewsh-common/src/main/java/com/viewsh/framework/common/pojo/CommonResult.java#L19-L37)
|
||
- [GlobalErrorCodeConstants.java](file://viewsh-framework/viewsh-common/src/main/java/com/viewsh/framework/common/exception/enums/GlobalErrorCodeConstants.java#L15-L41)
|
||
|
||
**章节来源**
|
||
- [CommonResult.java](file://viewsh-framework/viewsh-common/src/main/java/com/viewsh/framework/common/pojo/CommonResult.java#L1-L122)
|
||
- [GlobalErrorCodeConstants.java](file://viewsh-framework/viewsh-common/src/main/java/com/viewsh/framework/common/exception/enums/GlobalErrorCodeConstants.java#L1-L42)
|
||
|
||
### 分页与排序
|
||
- 分页参数
|
||
- pageNo：起始页（默认1，最小1）
|
||
- pageSize：每页数量（默认10，最大200；-1表示不分页导出）
|
||
- 排序参数
|
||
- 支持多字段排序，字段与顺序（asc/desc）
|
||
- 使用建议
|
||
- 导出场景使用-1不分页
|
||
- 接口文档中明确排序字段与顺序
|
||
|
||
```mermaid
|
||
classDiagram
|
||
class PageParam {
|
||
+Integer pageNo
|
||
+Integer pageSize
|
||
}
|
||
class SortablePageParam {
|
||
+SortingField[] sortingFields
|
||
}
|
||
class SortingField {
|
||
+String field
|
||
+String order
|
||
}
|
||
SortablePageParam --|> PageParam
|
||
SortablePageParam --> SortingField : "包含"
|
||
```
|
||
|
||
**图表来源**
|
||
- [PageParam.java](file://viewsh-framework/viewsh-common/src/main/java/com/viewsh/framework/common/pojo/PageParam.java#L13-L36)
|
||
- [SortablePageParam.java](file://viewsh-framework/viewsh-common/src/main/java/com/viewsh/framework/common/pojo/SortablePageParam.java#L14-L17)
|
||
- [SortingField.java](file://viewsh-framework/viewsh-common/src/main/java/com/viewsh/framework/common/pojo/SortingField.java#L14-L37)
|
||
|
||
**章节来源**
|
||
- [PageParam.java](file://viewsh-framework/viewsh-common/src/main/java/com/viewsh/framework/common/pojo/PageParam.java#L1-L37)
|
||
- [SortablePageParam.java](file://viewsh-framework/viewsh-common/src/main/java/com/viewsh/framework/common/pojo/SortablePageParam.java#L1-L19)
|
||
- [SortingField.java](file://viewsh-framework/viewsh-common/src/main/java/com/viewsh/framework/common/pojo/SortingField.java#L1-L38)
|
||
|
||
### 版本管理与路由
|
||
- RESTful版本前缀
|
||
- Admin接口：/admin-api/{module}/{resource}/v{version}
|
||
- App接口：/app-api/{module}/{resource}/v{version}
|
||
- RPC接口
|
||
- 统一前缀：/rpc-api/{service}
|
||
- 示例：/rpc-api/system
|
||
- 网关路由
|
||
- 根据前缀将请求转发至对应服务
|
||
- 版本号
|
||
- 各模块在ApiConstants中定义版本字符串，建议语义化版本
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A["请求路径"] --> B{"前缀判断"}
|
||
B --> |/admin-api/*| C["Admin服务"]
|
||
B --> |/app-api/*| D["App服务"]
|
||
B --> |/rpc-api/*| E["RPC服务"]
|
||
C --> F["模块路由"]
|
||
D --> F
|
||
E --> F
|
||
```
|
||
|
||
**图表来源**
|
||
- [WebProperties.java](file://viewsh-framework/viewsh-spring-boot-starter-web/src/main/java/com/viewsh/framework/web/config/WebProperties.java#L19-L22)
|
||
- [RpcConstants.java](file://viewsh-framework/viewsh-common/src/main/java/com/viewsh/framework/common/enums/RpcConstants.java#L14-L27)
|
||
- [ApiConstants.java（系统模块）](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/enums/ApiConstants.java#L10-L23)
|
||
- [ApiConstants.java（ops模块）](file://viewsh-module-ops/viewsh-module-ops-api/src/main/java/com/viewsh/module/ops/enums/ApiConstants.java#L10-L16)
|
||
|
||
**章节来源**
|
||
- [接口文档.md](file://docs/technical-overview/07-接口文档.md#L9-L72)
|
||
- [WebProperties.java](file://viewsh-framework/viewsh-spring-boot-starter-web/src/main/java/com/viewsh/framework/web/config/WebProperties.java#L1-L67)
|
||
- [RpcConstants.java](file://viewsh-framework/viewsh-common/src/main/java/com/viewsh/framework/common/enums/RpcConstants.java#L1-L41)
|
||
- [ApiConstants.java（系统模块）](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/enums/ApiConstants.java#L1-L24)
|
||
- [ApiConstants.java（ops模块）](file://viewsh-module-ops/viewsh-module-ops-api/src/main/java/com/viewsh/module/ops/enums/ApiConstants.java#L1-L16)
|
||
|
||
### 认证授权与令牌管理
|
||
- 令牌创建
|
||
- 通过OAuth2创建访问令牌与刷新令牌
|
||
- 令牌刷新
|
||
- 校验刷新令牌有效性、客户端匹配、过期时间
|
||
- 刷新成功后清理旧访问令牌
|
||
- 令牌存储
|
||
- 访问令牌使用Redis存储，便于快速校验与撤销
|
||
- 授权头
|
||
- Authorization: Bearer {token}
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant C as "客户端"
|
||
participant S as "系统服务"
|
||
participant M as "令牌服务"
|
||
participant R as "Redis"
|
||
C->>S : "登录/换取令牌"
|
||
S->>M : "创建访问令牌"
|
||
M-->>S : "返回访问令牌"
|
||
S-->>C : "返回令牌"
|
||
C->>S : "携带Bearer Token访问受保护接口"
|
||
S->>R : "校验访问令牌"
|
||
R-->>S : "校验结果"
|
||
S-->>C : "业务响应"
|
||
C->>S : "刷新令牌"
|
||
S->>M : "校验并刷新"
|
||
M->>R : "清理旧令牌"
|
||
M-->>S : "新令牌"
|
||
S-->>C : "新令牌"
|
||
```
|
||
|
||
**图表来源**
|
||
- [OAuth2TokenServiceImpl.java](file://viewsh-module-system/viewsh-module-system-server/src/main/java/com/viewsh/module/system/service/oauth2/OAuth2TokenServiceImpl.java#L62-L86)
|
||
- [OAuth2AccessTokenRedisDAO.java](file://viewsh-module-system/viewsh-module-system-server/src/main/java/com/viewsh/module/system/dal/redis/oauth2/OAuth2AccessTokenRedisDAO.java#L30-L37)
|
||
- [接口文档.md](file://docs/technical-overview/07-接口文档.md#L94-L105)
|
||
|
||
**章节来源**
|
||
- [OAuth2TokenServiceImpl.java](file://viewsh-module-system/viewsh-module-system-server/src/main/java/com/viewsh/module/system/service/oauth2/OAuth2TokenServiceImpl.java#L62-L86)
|
||
- [OAuth2AccessTokenRedisDAO.java](file://viewsh-module-system/viewsh-module-system-server/src/main/java/com/viewsh/module/system/dal/redis/oauth2/OAuth2AccessTokenRedisDAO.java#L1-L37)
|
||
- [OAuth2OpenControllerTest.java](file://viewsh-module-system/viewsh-module-system-server/src/test/java/com/viewsh/module/system/controller/admin/oauth2/OAuth2OpenControllerTest.java#L127-L149)
|
||
- [接口文档.md](file://docs/technical-overview/07-接口文档.md#L94-L105)
|
||
|
||
### 限流与幂等
|
||
- 限流
|
||
- 支持全局、用户、客户端IP、服务节点等维度
|
||
- 基于Redisson限流器实现，动态配置速率
|
||
- 幂等
|
||
- 基于注解与Redis实现，防止重复提交
|
||
- 默认超时窗口与提示信息可配置
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
S["进入受保护接口"] --> RL["限流检查"]
|
||
RL --> |允许| IDP["幂等检查"]
|
||
RL --> |拒绝| ER["返回限流错误"]
|
||
IDP --> |通过| EXEC["执行业务逻辑"]
|
||
IDP --> |冲突| EIDP["返回重复请求错误"]
|
||
EXEC --> RET["返回统一响应"]
|
||
```
|
||
|
||
**图表来源**
|
||
- [RateLimiter.java](file://viewsh-framework/viewsh-spring-boot-starter-protection/src/main/java/com/viewsh/framework/ratelimiter/core/annotation/RateLimiter.java#L24-L62)
|
||
- [RateLimiterAspect.java](file://viewsh-framework/viewsh-spring-boot-starter-protection/src/main/java/com/viewsh/framework/ratelimiter/core/aop/RateLimiterAspect.java#L24-L36)
|
||
- [RateLimiterRedisDAO.java](file://viewsh-framework/viewsh-spring-boot-starter-protection/src/main/java/com/viewsh/framework/ratelimiter/core/redis/RateLimiterRedisDAO.java#L29-L64)
|
||
- [Idempotent.java](file://viewsh-framework/viewsh-spring-boot-starter-protection/src/main/java/com/viewsh/framework/idempotent/core/annotation/Idempotent.java#L21-L43)
|
||
- [IdempotentAspect.java](file://viewsh-framework/viewsh-spring-boot-starter-protection/src/main/java/com/viewsh/framework/idempotent/core/aop/IdempotentAspect.java#L23-L38)
|
||
|
||
**章节来源**
|
||
- [RateLimiter.java](file://viewsh-framework/viewsh-spring-boot-starter-protection/src/main/java/com/viewsh/framework/ratelimiter/core/annotation/RateLimiter.java#L1-L62)
|
||
- [RateLimiterAspect.java](file://viewsh-framework/viewsh-spring-boot-starter-protection/src/main/java/com/viewsh/framework/ratelimiter/core/aop/RateLimiterAspect.java#L1-L36)
|
||
- [RateLimiterRedisDAO.java](file://viewsh-framework/viewsh-spring-boot-starter-protection/src/main/java/com/viewsh/framework/ratelimiter/core/redis/RateLimiterRedisDAO.java#L1-L66)
|
||
- [Idempotent.java](file://viewsh-framework/viewsh-spring-boot-starter-protection/src/main/java/com/viewsh/framework/idempotent/core/annotation/Idempotent.java#L1-L43)
|
||
- [IdempotentAspect.java](file://viewsh-framework/viewsh-spring-boot-starter-protection/src/main/java/com/viewsh/framework/idempotent/core/aop/IdempotentAspect.java#L1-L38)
|
||
|
||
### API文档生成与维护
|
||
- 生成与聚合
|
||
- 使用Knife4j（Swagger增强）自动生成与聚合微服务文档
|
||
- 统一入口：doc.html
|
||
- 标签排序
|
||
- 通过扩展为Tag添加x-order属性，实现文档侧边栏排序
|
||
- 开发注解
|
||
- 使用@Tag、@Operation、@Schema等标注接口与字段
|
||
|
||
```mermaid
|
||
graph LR
|
||
A["Controller"] --> B["@Tag/@Operation/@Schema"]
|
||
B --> C["Knife4j OpenAPI"]
|
||
C --> D["聚合文档 (doc.html)"]
|
||
```
|
||
|
||
**图表来源**
|
||
- [Knife4jOpenApiCustomizer.java](file://viewsh-framework/viewsh-spring-boot-starter-web/src/main/java/com/viewsh/framework/swagger/config/Knife4jOpenApiCustomizer.java#L56-L113)
|
||
- [接口文档.md](file://docs/technical-overview/07-接口文档.md#L45-L59)
|
||
|
||
**章节来源**
|
||
- [Knife4jOpenApiCustomizer.java](file://viewsh-framework/viewsh-spring-boot-starter-web/src/main/java/com/viewsh/framework/swagger/config/Knife4jOpenApiCustomizer.java#L56-L113)
|
||
- [接口文档.md](file://docs/technical-overview/07-接口文档.md#L45-L59)
|
||
|
||
### 安全与防护
|
||
- 请求签名
|
||
- 基于时间戳、随机数、参数排序与密钥计算签名，防重放与篡改
|
||
- 限流与幂等
|
||
- 已在上文详述
|
||
- 访问日志
|
||
- 可选的访问日志过滤器与注解，记录操作模块、名称与类型
|
||
|
||
**章节来源**
|
||
- [ApiSignatureAspect.java](file://viewsh-framework/viewsh-spring-boot-starter-protection/src/main/java/com/viewsh/framework/signature/core/aop/ApiSignatureAspect.java#L1-L40)
|
||
- [ApiAccessLog.java](file://viewsh-framework/viewsh-spring-boot-starter-web/src/main/java/com/viewsh/framework/apilog/core/annotation/APIAccessLog.java#L47-L65)
|
||
- [ApiAccessLogFilter.java](file://viewsh-framework/viewsh-spring-boot-starter-web/src/main/java/com/viewsh/framework/apilog/core/filter/APIAccessLogFilter.java#L1-L27)
|
||
|
||
## 依赖关系分析
|
||
- 统一响应与错误码贯穿各模块，确保接口一致性
|
||
- 分页与排序模型被大量控制器使用，形成跨模块契约
|
||
- 网关前缀与RPC常量定义了清晰的路由边界
|
||
- 安全组件通过AOP织入，对业务透明
|
||
- 文档聚合依赖Knife4j与Tag注解
|
||
|
||
```mermaid
|
||
graph TB
|
||
CR["CommonResult"] --> EC["GlobalErrorCodeConstants"]
|
||
PP["PageParam/SortablePageParam"] --> CR
|
||
WP["WebProperties"] --> WFU["WebFrameworkUtils"]
|
||
RC["RpcConstants"] --> WP
|
||
OAT["OAuth2TokenServiceImpl"] --> OAR["OAuth2AccessTokenRedisDAO"]
|
||
SIG["ApiSignatureAspect"] --> CR
|
||
RL["RateLimiterAspect/DAO"] --> CR
|
||
IDP["IdempotentAspect"] --> CR
|
||
K4J["Knife4jOpenApiCustomizer"] --> CR
|
||
```
|
||
|
||
**图表来源**
|
||
- [CommonResult.java](file://viewsh-framework/viewsh-common/src/main/java/com/viewsh/framework/common/pojo/CommonResult.java#L1-L122)
|
||
- [GlobalErrorCodeConstants.java](file://viewsh-framework/viewsh-common/src/main/java/com/viewsh/framework/common/exception/enums/GlobalErrorCodeConstants.java#L1-L42)
|
||
- [PageParam.java](file://viewsh-framework/viewsh-common/src/main/java/com/viewsh/framework/common/pojo/PageParam.java#L1-L37)
|
||
- [WebProperties.java](file://viewsh-framework/viewsh-spring-boot-starter-web/src/main/java/com/viewsh/framework/web/config/WebProperties.java#L1-L67)
|
||
- [WebFrameworkUtils.java](file://viewsh-framework/viewsh-spring-boot-starter-web/src/main/java/com/viewsh/framework/web/core/util/WebFrameworkUtils.java#L1-L184)
|
||
- [RpcConstants.java](file://viewsh-framework/viewsh-common/src/main/java/com/viewsh/framework/common/enums/RpcConstants.java#L1-L41)
|
||
- [OAuth2TokenServiceImpl.java](file://viewsh-module-system/viewsh-module-system-server/src/main/java/com/viewsh/module/system/service/oauth2/OAuth2TokenServiceImpl.java#L62-L86)
|
||
- [OAuth2AccessTokenRedisDAO.java](file://viewsh-module-system/viewsh-module-system-server/src/main/java/com/viewsh/module/system/dal/redis/oauth2/OAuth2AccessTokenRedisDAO.java#L1-L37)
|
||
- [ApiSignatureAspect.java](file://viewsh-framework/viewsh-spring-boot-starter-protection/src/main/java/com/viewsh/framework/signature/core/aop/ApiSignatureAspect.java#L1-L40)
|
||
- [RateLimiterAspect.java](file://viewsh-framework/viewsh-spring-boot-starter-protection/src/main/java/com/viewsh/framework/ratelimiter/core/aop/RateLimiterAspect.java#L1-L36)
|
||
- [RateLimiterRedisDAO.java](file://viewsh-framework/viewsh-spring-boot-starter-protection/src/main/java/com/viewsh/framework/ratelimiter/core/redis/RateLimiterRedisDAO.java#L1-L66)
|
||
- [IdempotentAspect.java](file://viewsh-framework/viewsh-spring-boot-starter-protection/src/main/java/com/viewsh/framework/idempotent/core/aop/IdempotentAspect.java#L1-L38)
|
||
- [Knife4jOpenApiCustomizer.java](file://viewsh-framework/viewsh-spring-boot-starter-web/src/main/java/com/viewsh/framework/swagger/config/Knife4jOpenApiCustomizer.java#L56-L113)
|
||
|
||
**章节来源**
|
||
- [CommonResult.java](file://viewsh-framework/viewsh-common/src/main/java/com/viewsh/framework/common/pojo/CommonResult.java#L1-L122)
|
||
- [PageParam.java](file://viewsh-framework/viewsh-common/src/main/java/com/viewsh/framework/common/pojo/PageParam.java#L1-L37)
|
||
- [WebProperties.java](file://viewsh-framework/viewsh-spring-boot-starter-web/src/main/java/com/viewsh/framework/web/config/WebProperties.java#L1-L67)
|
||
- [RpcConstants.java](file://viewsh-framework/viewsh-common/src/main/java/com/viewsh/framework/common/enums/RpcConstants.java#L1-L41)
|
||
- [OAuth2TokenServiceImpl.java](file://viewsh-module-system/viewsh-module-system-server/src/main/java/com/viewsh/module/system/service/oauth2/OAuth2TokenServiceImpl.java#L62-L86)
|
||
- [OAuth2AccessTokenRedisDAO.java](file://viewsh-module-system/viewsh-module-system-server/src/main/java/com/viewsh/module/system/dal/redis/oauth2/OAuth2AccessTokenRedisDAO.java#L1-L37)
|
||
- [ApiSignatureAspect.java](file://viewsh-framework/viewsh-spring-boot-starter-protection/src/main/java/com/viewsh/framework/signature/core/aop/ApiSignatureAspect.java#L1-L40)
|
||
- [RateLimiterAspect.java](file://viewsh-framework/viewsh-spring-boot-starter-protection/src/main/java/com/viewsh/framework/ratelimiter/core/aop/RateLimiterAspect.java#L1-L36)
|
||
- [RateLimiterRedisDAO.java](file://viewsh-framework/viewsh-spring-boot-starter-protection/src/main/java/com/viewsh/framework/ratelimiter/core/redis/RateLimiterRedisDAO.java#L1-L66)
|
||
- [IdempotentAspect.java](file://viewsh-framework/viewsh-spring-boot-starter-protection/src/main/java/com/viewsh/framework/idempotent/core/aop/IdempotentAspect.java#L1-L38)
|
||
- [Knife4jOpenApiCustomizer.java](file://viewsh-framework/viewsh-spring-boot-starter-web/src/main/java/com/viewsh/framework/swagger/config/Knife4jOpenApiCustomizer.java#L56-L113)
|
||
|
||
## 性能考量
|
||
- 限流策略
|
||
- 建议按接口粒度配置不同阈值，结合用户/IP/节点维度
|
||
- 动态配置速率，避免硬编码
|
||
- 幂等设计
|
||
- 对写操作强制幂等，减少重试带来的副作用
|
||
- 缓存与存储
|
||
- 访问令牌使用Redis，降低数据库压力
|
||
- 文档生成
|
||
- 聚合文档仅在必要时刷新，避免频繁扫描
|
||
|
||
## 故障排查指南
|
||
- 统一响应与错误码
|
||
- 检查响应体中的code与msg，定位业务异常
|
||
- 使用全局错误码映射快速识别HTTP与业务错误
|
||
- 认证授权
|
||
- 确认Authorization头格式与令牌有效性
|
||
- 校验刷新令牌是否过期或客户端不匹配
|
||
- 限流与幂等
|
||
- 若频繁收到限流错误，调整限流配置或客户端退避
|
||
- 幂等冲突时，检查请求键与超时设置
|
||
- 文档与路由
|
||
- 确认请求前缀与目标服务匹配
|
||
- 通过Knife4j确认接口暴露情况
|
||
|
||
**章节来源**
|
||
- [CommonResult.java](file://viewsh-framework/viewsh-common/src/main/java/com/viewsh/framework/common/pojo/CommonResult.java#L72-L121)
|
||
- [GlobalErrorCodeConstants.java](file://viewsh-framework/viewsh-common/src/main/java/com/viewsh/framework/common/exception/enums/GlobalErrorCodeConstants.java#L17-L41)
|
||
- [OAuth2TokenServiceImpl.java](file://viewsh-module-system/viewsh-module-system-server/src/main/java/com/viewsh/module/system/service/oauth2/OAuth2TokenServiceImpl.java#L72-L86)
|
||
- [OAuth2AccessTokenRedisDAO.java](file://viewsh-module-system/viewsh-module-system-server/src/main/java/com/viewsh/module/system/dal/redis/oauth2/OAuth2AccessTokenRedisDAO.java#L30-L37)
|
||
- [RateLimiterAspect.java](file://viewsh-framework/viewsh-spring-boot-starter-protection/src/main/java/com/viewsh/framework/ratelimiter/core/aop/RateLimiterAspect.java#L24-L36)
|
||
- [IdempotentAspect.java](file://viewsh-framework/viewsh-spring-boot-starter-protection/src/main/java/com/viewsh/framework/idempotent/core/aop/IdempotentAspect.java#L23-L38)
|
||
- [Knife4jOpenApiCustomizer.java](file://viewsh-framework/viewsh-spring-boot-starter-web/src/main/java/com/viewsh/framework/swagger/config/Knife4jOpenApiCustomizer.java#L56-L113)
|
||
|
||
## 结论
|
||
本规范以现有实现为基础，明确了平台API的统一响应、错误码、分页排序、版本与路由、认证授权、限流与幂等、文档生成与维护、测试与调试以及安全防护要求。建议在后续迭代中持续完善各模块的版本号与路由前缀，强化安全组件的配置与监控，确保跨模块一致性与可维护性。
|
||
|
||
## 附录
|
||
- API测试最佳实践
|
||
- 使用HTTP客户端环境文件组织请求
|
||
- 针对认证、限流、幂等场景编写集成测试
|
||
- 调试工具
|
||
- Knife4j文档入口与接口调试
|
||
- 访问日志与错误日志辅助定位问题
|
||
|
||
**章节来源**
|
||
- [接口文档.md](file://docs/technical-overview/07-接口文档.md#L45-L106) |