# 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 实时消息推送 - 在线状态管理 - 即时通讯支持 ## 启动配置 ### 应用启动类 ```java @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秒 ## 依赖关系 ### 核心依赖 ```xml com.java110 java110-service com.java110 java110-interface org.springframework.boot spring-boot-starter-websocket ``` ### 服务接口依赖 模块通过 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 相关组件 ### 启动命令 ```bash # 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)** - 权限验证阶段的详细说明 - **[服务分发阶段说明.md](服务分发阶段说明.md)** - 服务分发阶段的详细说明 - **[业务处理阶段说明.md](业务处理阶段说明.md)** - 业务处理阶段的详细说明 - **[响应返回阶段说明.md](响应返回阶段说明.md)** - 响应返回阶段的详细说明 ### 处理流程概览 ``` 客户端请求 ↓ 请求接收阶段 (AppController) ↓ 权限验证阶段 (IPrivilegeSMO) ↓ 服务分发阶段 (IApiSMO → ApiSMOImpl) ↓ 业务处理阶段 (IApiServiceSMO → ApiServiceSMOImpl) ↓ 响应返回阶段 (统一响应封装) ``` ## 注意事项 1. **服务依赖**: 启动前确保依赖的微服务已注册到服务发现中心 2. **配置管理**: 根据部署环境选择对应的配置文件 3. **安全配置**: 定期更新JWT密钥和微信配置信息 4. **性能优化**: 根据实际业务量调整连接池和超时配置 5. **文档参考**: 详细的技术实现请参考各阶段说明文档 ## 版本信息 - **当前版本**: 1.0-SNAPSHOT - **Spring Boot**: 2.x - **Spring Cloud**: 对应版本 - **JDK**: 1.8+ ---