youlai-mall网关配置详解：Spring Cloud Gateway + Knife4j聚合文档
项目地址: https://gitcode.com/gh_mirrors/yo/youlai-mall youlai-mall是基于Spring Boot 3、Spring Cloud & Alibaba 2022构建的开源全栈商城项目，其中网关模块采用Spring Cloud Gateway实现请求路由与负载均衡，并集成Knife4j实现API文档的聚合管理，为开发者提供统一的接口调试与管理平台。
一、Spring Cloud Gateway核心配置
1.1 安全配置（SecurityConfig）
网关安全配置主要通过SecurityWebFilterChain实现请求拦截与权限控制，核心代码位于youlai-gateway/src/main/java/com/youlai/gateway/config/SecurityConfig.java：
@Bean
public SecurityWebFilterChain securityFilterChain(ServerHttpSecurity http) {
http
.authorizeExchange(exchange -> {
if (CollectionUtil.isNotEmpty(blacklistPaths)) {
exchange.pathMatchers(Convert.toStrArray(blacklistPaths)).authenticated();
}
exchange.anyExchange().permitAll();
})
.csrf(ServerHttpSecurity.CsrfSpec::disable);
return http.build();
}
功能说明：
- 通过
blacklistPaths配置需要认证的路径 - 禁用CSRF保护以支持API接口调试
- 默认允许所有请求访问（实际生产环境需根据业务调整）
1.2 启动类配置（GatewayApplication）
网关应用入口类通过@EnableDiscoveryClient启用服务发现，实现动态路由功能，代码位于youlai-gateway/src/main/java/com/youlai/gateway/GatewayApplication.java：
@SpringBootApplication
@EnableDiscoveryClient
public class GatewayApplication {
public static void main(String[] args) {
SpringApplication.run(GatewayApplication.class, args);
}
}
二、Knife4j聚合文档配置
2.1 OpenAPI基础配置
项目通过SpringDoc + Knife4j实现API文档生成，核心配置类为common-apidoc/src/main/java/com/youlai/common/apidoc/OpenApiConfig.java，主要功能包括：
@Bean
public OpenAPI apiInfo() {
return new OpenAPI()
.components(new Components()
.addSecuritySchemes(HttpHeaders.AUTHORIZATION,
new SecurityScheme()
.type(SecurityScheme.Type.OAUTH2)
.name(HttpHeaders.AUTHORIZATION)
.flows(new OAuthFlows()
.password(new OAuthFlow()
.tokenUrl(tokenUrl)
.refreshUrl(tokenUrl)
)
)
.in(SecurityScheme.In.HEADER)
.scheme("Bearer")
.bearerFormat("JWT")
)
)
.addSecurityItem(new SecurityRequirement().addList(HttpHeaders.AUTHORIZATION))
.info(new Info()
.title(apiDocInfoProperties.getTitle())
.version(apiDocInfoProperties.getVersion())
.description(apiDocInfoProperties.getDescription())
);
}
关键特性：
- 配置OAuth2密码模式认证
- 全局添加JWT令牌认证头
- 支持接口文档标题、版本、描述等元信息自定义
2.2 文档聚合访问
完成配置后，启动网关服务即可通过以下地址访问聚合API文档：
- Knife4j增强版界面：
http://localhost:9999/doc.html - 标准OpenAPI文档：
http://localhost:9999/v3/api-docs
三、快速使用指南
3.1 项目拉取
git clone https://gitcode.com/gh_mirrors/yo/youlai-mall
3.2 网关模块启动
- 进入项目根目录，执行Maven构建：
mvn clean package -DskipTests
- 启动网关服务：
java -jar youlai-gateway/target/youlai-gateway.jar
- 访问API文档：打开浏览器访问
http://localhost:9999/doc.html
四、常见问题解决
4.1 文档无法访问
检查网关application.yml中是否配置正确的路由规则，确保将/doc.html、/v3/api-docs/**等路径路由到对应的服务。
4.2 认证失败
确认youlai-auth服务已启动，且OpenApiConfig中配置的tokenUrl与认证服务地址一致。
五、总结
youlai-mall通过Spring Cloud Gateway实现了微服务架构下的统一入口管理，结合Knife4j聚合文档功能，为开发者提供了便捷的接口调试体验。核心配置文件集中在网关模块与公共API文档模块，通过简单的配置即可实现强大的路由与文档管理功能，是快速构建微服务商城的理想选择。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
