README.md
Service-API 网关模块
模块概述
service-api 是 HC 小区管理系统的网关模块，作为整个微服务架构的统一入口，承担着请求路由、认证授权、API文档管理、请求过滤等核心职责。该模块基于 Spring Cloud 技术栈构建，采用命令驱动架构设计。
技术架构
核心框架
- Spring Boot 2.x - 应用基础框架
- Spring Cloud - 微服务治理
- Spring Cloud OpenFeign - 服务间调用
- Swagger 2 - API文档生成
- WebSocket - 实时通信支持
架构特点
- 统一入口: 所有外部请求的统一接入点
- 服务发现: 集成 Eureka 服务注册与发现
- 负载均衡: 内置 Ribbon 负载均衡器
- API文档: 自动生成 Swagger API 文档
- 认证授权: JWT Token 认证机制
- 请求过滤: 多层过滤器链处理
模块结构
service-api/
├── src/main/java/com/java110/api/
│ ├── aop/ # 切面编程
│ ├── components/ # 组件处理
│ ├── configuration/ # 配置类
│ │ ├── ServiceConfiguration.java # 服务配置
│ │ └── WebSocketConfig.java # WebSocket配置
│ ├── controller/ # 控制器层
│ │ ├── app/ # 移动端控制器
│ │ │ ├── file/ # 文件处理
│ │ │ ├── payment/ # 支付处理
│ │ │ ├── ActivitiController.java
│ │ │ ├── AppController.java
│ │ │ ├── AppTokenController.java
│ │ │ ├── EnvController.java
│ │ │ ├── OwnerController.java
│ │ │ ├── PaymentController.java
│ │ │ ├── PropertyController.java
│ │ │ └── WechatGatewayController.java
│ │ ├── component/ # 组件控制器
│ │ ├── goods/ # 商品控制器
│ │ ├── FlowController.java
│ │ ├── HomeController.java
│ │ └── SystemErrorController.java
│ ├── filter/ # 过滤器
│ │ └── JwtFilter.java # JWT认证过滤器
│ ├── importData/ # 数据导入
│ ├── listener/ # 事件监听器
│ ├── properties/ # 属性配置
│ ├── rest/ # REST接口
│ │ ├── CreatePluginsConfig.java
│ │ └── RestApi.java
│ ├── smo/ # 服务管理对象
│ │ ├── activiti/ # 工作流服务
│ │ ├── addOwner/ # 业主添加服务
│ │ ├── api/ # API服务
│ │ ├── assetExport/ # 资产导出
│ │ ├── assetImport/ # 资产导入
│ │ ├── basePrivilege/ # 基础权限
│ │ ├── cache/ # 缓存服务
│ │ ├── common/ # 通用服务
│ │ ├── configMenu/ # 菜单配置
│ │ ├── devServiceProvide/ # 开发服务提供
│ │ ├── dict/ # 字典服务
│ │ ├── fee/ # 费用服务
│ │ ├── file/ # 文件服务
│ │ ├── impl/ # 服务实现
│ │ ├── login/ # 登录服务
│ │ ├── mapping/ # 映射服务
│ │ ├── menu/ # 菜单服务
│ │ ├── meterWaterImport/ # 水电表导入
│ │ ├── msg/ # 消息服务
│ │ ├── org/ # 组织服务
│ │ ├── payment/ # 支付服务
│ │ ├── privilege/ # 权限服务
│ │ ├── staff/ # 员工服务
│ │ ├── sys/ # 系统服务
│ │ ├── undo/ # 撤销服务
│ │ ├── wechatGateway/ # 微信网关
│ │ └── 核心接口类文件
│ ├── websocket/ # WebSocket处理
│ ├── ApiApplicationStart.java # 应用启动类
│ └── package-info.java
├── src/main/resources/
│ ├── static/ # 静态资源
│ ├── application-dev.yml # 开发环境配置
│ ├── application-dynamic.yml # 动态配置
│ ├── application-zihao.yml # 测试环境配置
│ ├── application.yml # 主配置文件
│ ├── banner.txt # 启动横幅
│ ├── java110.properties # 系统属性
│ └── wechatAuth.properties # 微信认证配置
├── pom.xml # Maven配置
├── pom-boot.xml # Spring Boot配置
└── pom-cloud.xml # Spring Cloud配置
核心功能
1. 网关路由
- 统一请求入口，支持 RESTful API
- 动态服务路由与负载均衡
- 请求转发与响应处理
2. 认证授权
- JWT Token 认证机制
- 权限验证与访问控制
- 白名单配置（登录、注册等接口免认证）
3. API文档
- 自动生成 Swagger API 文档
- 在线接口测试
- API版本管理
4. 请求过滤
- 请求参数验证
- 安全防护（XSS、SQL注入等）
- 请求日志记录
5. 文件处理
- 文件上传下载（支持50MB大文件）
- 图片、视频等多媒体文件处理
- 静态资源服务
6. 支付网关
- 微信支付集成
- 银联支付支持
- 支付回调处理
7. 实时通信
- WebSocket 实时消息推送
- 在线状态管理
- 即时通讯支持
启动配置
应用启动类
@SpringBootApplication
@EnableDiscoveryClient
@EnableFeignClients
@EnableSwagger2
public class ApiApplicationStart {
public static void main(String[] args) {
SpringApplication.run(ApiApplicationStart.class, args);
}
}
主要配置项
- 服务发现: 集成 Eureka 服务注册中心
- Feign客户端: 支持服务间调用
- Swagger文档: 自动生成API文档
- 文件上传: 最大支持50MB文件
- 超时配置: 连接超时10秒，读取超时10秒
依赖关系
核心依赖
<dependencies>
<dependency>
<groupId>com.java110</groupId>
<artifactId>java110-service</artifactId>
</dependency>
<dependency>
<groupId>com.java110</groupId>
<artifactId>java110-interface</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-websocket</artifactId>
</dependency>
</dependencies>
服务接口依赖
模块通过 Feign 客户端依赖以下服务接口：
com.java110.intf.acct- 账户服务com.java110.intf.code- 编码服务com.java110.intf.common- 通用服务com.java110.intf.community- 社区服务com.java110.intf.demo- 演示服务com.java110.intf.dev- 开发服务com.java110.intf.fee- 费用服务com.java110.intf.goods- 商品服务com.java110.intf.job- 任务服务com.java110.intf.oa- OA服务com.java110.intf.order- 订单服务com.java110.intf.report- 报表服务com.java110.intf.store- 店铺服务com.java110.intf.user- 用户服务
部署说明
环境要求
- JDK 1.8+
- Maven 3.6+
- Spring Boot 2.x
- Spring Cloud 相关组件
启动命令
# Spring Boot 模式
mvn spring-boot:run -f pom-boot.xml
# Spring Cloud 模式
mvn spring-boot:run -f pom-cloud.xml
配置说明
application.yml- 主配置文件application-dev.yml- 开发环境配置java110.properties- 系统属性配置wechatAuth.properties- 微信认证配置
API文档访问
启动应用后，可通过以下地址访问API文档：
http://localhost:8008/swagger-ui.html
安全配置
JWT过滤器配置
模块配置了JWT认证过滤器，支持以下免认证接口：
- 登录注册相关接口
- 支付回调接口
- 文件下载接口
- 微信相关接口
- 公共信息查询接口
文件上传限制
- 单文件最大: 50MB
- 请求最大: 50MB
- 支持格式: 图片、视频、文档等
监控与日志
- 集成 Spring Boot Actuator 监控端点
- SLF4J + Logback 日志框架
- 请求链路追踪
- 性能监控指标
网关调度机制详细说明
为了更好地理解网关的工作机制，我们提供了详细的阶段说明文档：
网关处理流程文档
- 网关调度介绍.md - 完整的网关调度机制概述
- 请求接收阶段说明.md - 请求接收阶段的详细说明
- 权限验证阶段说明.md - 权限验证阶段的详细说明
- 服务分发阶段说明.md - 服务分发阶段的详细说明
- 业务处理阶段说明.md - 业务处理阶段的详细说明
- 响应返回阶段说明.md - 响应返回阶段的详细说明
处理流程概览
客户端请求
↓
请求接收阶段 (AppController)
↓
权限验证阶段 (IPrivilegeSMO)
↓
服务分发阶段 (IApiSMO → ApiSMOImpl)
↓
业务处理阶段 (IApiServiceSMO → ApiServiceSMOImpl)
↓
响应返回阶段 (统一响应封装)
注意事项
- 服务依赖: 启动前确保依赖的微服务已注册到服务发现中心
- 配置管理: 根据部署环境选择对应的配置文件
- 安全配置: 定期更新JWT密钥和微信配置信息
- 性能优化: 根据实际业务量调整连接池和超时配置
- 文档参考: 详细的技术实现请参考各阶段说明文档
版本信息
- 当前版本: 1.0-SNAPSHOT
- Spring Boot: 2.x
- Spring Cloud: 对应版本
- JDK: 1.8+