README.md 9.79 KB

Edit Raw Blame History


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+