java110-interface 模块技术文档

模块概述

java110-interface 是 MicroCommunity 微服务架构中的接口定义模块，基于 Spring Cloud OpenFeign 技术栈，为系统内各微服务提供统一的 Feign 客户端接口定义。本模块包含 584 个业务接口，覆盖社区管理系统的所有核心业务领域。

技术架构

核心组件

1. Feign 客户端配置

   • FeignConfiguration: Feign 客户端全局配置类
   • UserErrorDecoder: 自定义错误解码器，处理服务调用异常

2. 接口定义规范

   • 所有接口均使用 @FeignClient 注解声明
   • 统一的服务间调用异常处理机制
   • 支持日志级别动态配置

技术栈

• Spring Cloud OpenFeign: 微服务接口调用框架
• Spring Boot: 应用基础框架
• Maven: 项目构建工具
• JUnit: 单元测试框架

依赖关系

<dependencies>
    <dependency>
        <groupId>com.java110</groupId>
        <artifactId>java110-bean</artifactId>
        <scope>provided</scope>
    </dependency>
    <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-starter-openfeign</artifactId>
        <scope>provided</scope>
    </dependency>
</dependencies>

核心功能模块

1. 用户管理模块 (73个接口)

• 业主管理: IOwnerInnerServiceSMO, IOwnerV1InnerServiceSMO
• 员工管理: IStaffAppAuthInnerServiceSMO, IStaffCommunityV1InnerServiceSMO
• 权限管理: IPrivilegeGroupV1InnerServiceSMO, IPrivilegeUserV1InnerServiceSMO
• 组织架构: IOrgInnerServiceSMO, IOrgV1InnerServiceSMO
• 车辆管理: IOwnerCarInnerServiceSMO, IOwnerCarV1InnerServiceSMO

2. 费用管理模块 (60个接口)

• 费用配置: IFeeConfigInnerServiceSMO, IPayFeeConfigV1InnerServiceSMO
• 收费管理: IFeeInnerServiceSMO, IPayFeeV1InnerServiceSMO
• 费用折扣: IFeeDiscountInnerServiceSMO, IFeeDiscountRuleInnerServiceSMO
• 打印管理: IFeePrintPageV1InnerServiceSMO, IFeePrintSpecInnerServiceSMO
• 临时车费: ITempCarFeeConfigInnerServiceSMO, IComputeTempCarFee

3. 社区管理模块 (99个接口)

• 社区基础: ICommunityInnerServiceSMO, ICommunityV1InnerServiceSMO
• 楼栋单元: IFloorInnerServiceSMO, IUnitInnerServiceSMO
• 房间管理: IRoomInnerServiceSMO, IRoomV1InnerServiceSMO
• 巡检管理: IInspectionInnerServiceSMO, IInspectionPlanInnerServiceSMO
• 维修管理: IRepairInnerServiceSMO, IRepairUserInnerServiceSMO
• 停车场管理: IParkingAreaInnerServiceSMO, IParkingSpaceInnerServiceSMO

4. 其他业务模块

• 订单管理: IOrderInnerServiceSMO, ICordersInnerServiceSMO
• 商品管理: goods 目录下的接口
• OA系统: oa 目录下的接口
• 报表管理: report 目录下的接口
• 供应链管理: scm 目录下的接口

配置说明

Feign 客户端配置

@Configuration
public class FeignConfiguration {
    @Bean
    public ErrorDecoder errorDecoder() {
        return new UserErrorDecoder();
    }

    @Bean
    Logger.Level feignLoggerLevel() {
        if (SystemLogDto.getLogSwatch()) {
            return Logger.Level.FULL;
        } else {
            return Logger.Level.NONE;
        }
    }
}

自定义错误解码器

public class UserErrorDecoder implements ErrorDecoder {
    public Exception decode(String methodKey, Response response) {
        // 处理服务调用异常，400+状态码转换为 HystrixBadRequestException
        // 其他异常记录日志并返回 RuntimeException
    }
}

使用示例

1. 服务调用示例

@Autowired
private IUserInnerServiceSMO userInnerService;

// 查询用户信息
List<UserDto> users = userInnerService.getUsers(userDto);

// 查询员工数量
int staffCount = userInnerService.getStaffCount(userDto);

2. 接口定义规范

@FeignClient(name = "user-service", configuration = {FeignConfiguration.class})
@RequestMapping("/userApi")
public interface IUserInnerServiceSMO {

    @RequestMapping(value = "/getUserInfo", method = RequestMethod.GET)
    List<UserDto> getUserInfo(@RequestParam("userIds") String[] userIds);

    @RequestMapping(value = "/getStaffs", method = RequestMethod.POST)
    List<UserDto> getStaffs(@RequestBody UserDto userDto);
}

开发规范

1. 接口命名规范

• 接口类名以 I 开头，以 InnerServiceSMO 结尾
• 方法名使用驼峰命名法，清晰表达业务功能
• 版本控制使用 V1 后缀标识

2. 参数传递规范

• 简单参数使用 @RequestParam 注解
• 复杂对象使用 @RequestBody 注解
• 批量查询支持数组参数

3. 异常处理规范

• 服务调用异常由 UserErrorDecoder 统一处理
• 400+ 状态码转换为 HystrixBadRequestException
• 其他异常记录详细日志信息

目录结构

java110-interface/
├── src/main/java/com/java110/
│   ├── config/                    # 配置类
│   │   ├── feign/                # Feign 配置
│   │   │   ├── FeignConfiguration.java
│   │   │   └── UserErrorDecoder.java
│   │   └── App.java              # 启动类
│   └── intf/                     # 业务接口定义
│       ├── user/                 # 用户管理接口 (73个)
│       ├── fee/                  # 费用管理接口 (60个)
│       ├── community/            # 社区管理接口 (99个)
│       ├── order/                # 订单管理接口 (4个)
│       └── ...                   # 其他业务接口
├── pom.xml                       # Maven 配置
└── README.md                     # 本文档

注意事项

1. 服务发现: 确保目标服务在服务注册中心可用
2. 超时配置: 根据业务需求合理设置调用超时时间
3. 熔断机制: 结合 Hystrix 实现服务熔断和降级
4. 日志管理: 通过系统日志开关控制 Feign 日志级别

版本信息

• 当前版本: 1.0-SNAPSHOT
• 父项目: MicroCommunity
• 打包方式: jar

---