📋 文档信息

项目	内容
文档版本	v1.0
生效日期	2025年12月
适用项目	EpochCloud微服务项目+EpochBoot项目
制定部门	Epoch架构组

🏗️ 包结构规范

1. 包层次结构标准

com.epoch.{系统}.{模块}.{层级}[.{子包}]

2. 包命名规范表

包名	英文全称	中文含义	示例	必须性	说明
api	Application Programming Interface	对外接口层	com.epoch.sys.role.api	✅ 必须	定义对外接口契约
feign	Feign Client	Feign客户端	com.epoch.sys.role.api.feign	✅ 必须	Feign相关类
impl	Implementation	实现类	com.epoch.sys.role.api.feign.impl	✅ 必须	接口实现类
service	Business Service	业务服务层	com.epoch.sys.role.service	✅ 必须	业务逻辑服务
converter	Object Converter	对象转换器	com.epoch.sys.role.converter	✅ 必须	对象转换处理
controller	Web Controller	Web控制器	com.epoch.sys.role.controller	✅ 必须	Web请求处理
repo	Repository	数据仓储层	com.epoch.sys.role.repo	✅ 必须	数据访问层
entity	Data Entity	数据实体	com.epoch.sys.role.repo.entity	✅ 必须	数据库实体类
mapper	Data Mapper	数据映射器	com.epoch.sys.role.repo.mapper	✅ 必须	MyBatis Mapper接口
dto	Data Transfer Object	数据传输对象	com.epoch.sys.role.api.dto	✅ 必须	请求参数对象
vo	Value Object	值对象	com.epoch.sys.role.api.vo	✅ 必须	响应结果对象

整体项目结构如下：

3. 包命名规则

必须遵守的规则

• 全小写命名：api、service、controller
• 使用单数名词：entity、mapper、converter
• 避免缩写：使用完整单词
• 层次清晰：按照功能分层

❌ 严格禁止的规则

• 禁止大写：不能使用 API、Service
• 禁止复数：不能使用 entities、services
• 禁止缩写：不能使用 svc、ctrl
• 禁止下划线：不能使用 web_controller

📄 类命名规范

1. 类命名规范表

类别	命名模式	示例	说明
Feign接口	{模块名}Feign	RoleFeign	Feign客户端接口
Feign实现	{模块名}FeignImpl	RoleFeignImpl	Feign接口实现类
Controller	{模块名}Controller	RoleController	Web控制器
Service接口	{模块名}Service	RoleService	业务服务接口
Service实现	{模块名}ServiceImpl	RoleServiceImpl	业务服务实现类
Converter	{模块名}Converter	RoleConverter	对象转换器
Repo Service	{模块名}RepoService	RoleRepoService	数据访问服务
Entity	{模块名}Entity	RoleEntity	数据库实体类
Mapper	{模块名}Mapper	RoleMapper	MyBatis Mapper接口
DTO	{操作}{模块名}DTO	CreateRoleDTO	创建操作DTO
DTO	{操作}{模块名}DTO	UpdateRoleDTO	更新操作DTO
DTO	{模块名}QueryDTO	RoleQueryDTO	查询参数DTO
VO	{模块名}VO	RoleVO	基础视图对象
VO	{模块名}DetailVO	RoleDetailVO	详情视图对象
VO	{模块名}ListVO	RoleListVO	列表视图对象

2. 通用命名规则

必须遵守的规则

• 使用大驼峰命名法：RoleService、RoleController
• 名词或名词短语：准确表达类的职责
• 避免缩写：使用完整单词
• 语义明确：通过名称可知功能

❌ 严格禁止的规则

• 避免Manager、Processor等泛化名称
• 避免"I"前缀：不使用 IRoleService
• 避免下划线：不使用 Role_Service
• 避免首字母小写：不使用 roleService

3. 特殊类命名规则

接口命名

<JAVA>

// ✅ 正确示例
public interface RoleFeign {}
public interface RoleService {}
public interface Converter {}
// ❌ 错误示例
public interface IRoleService {}      // 避免I前缀
public interface RoleFeignClient {}   // 避免冗余

实现类命名

<JAVA>

// ✅ 正确示例
@Service
public class RoleServiceImpl implements RoleService {}
@RestController  
public class RoleFeignImpl implements RoleFeign {}
// ❌ 错误示例
public class RoleServiceImp {}        // 缩写错误
public class RoleServiceManager {}    // 泛化名称

DTO/VO命名

// ✅ 正确示例
public class CreateRoleDTO {}         // 创建操作
public class UpdateRoleDTO {}         // 更新操作
public class RoleQueryDTO {}          // 查询参数
public class RoleVO {}                // 基础视图
public class RoleDetailVO {}          // 详情视图
// ❌ 错误示例
public class RoleDto {}               // 缩写错误
public class RoleVo {}                // 缩写错误
public class RoleModel {}             // 不明确

🎯 实际应用示例

1. 完整包结构示例

<TEXT>

com.epoch.sys.role/

├── api/

│ ├── feign/

│ │ └── RoleFeign.java

│ ├── dto/

│ │ ├── CreateRoleDTO.java

│ │ ├── UpdateRoleDTO.java

│ │ └── RoleQueryDTO.java

│ └── vo/

│ ├── RoleVO.java

│ └── RoleDetailVO.java

├── feign/

│ └── impl/

│ └── RoleFeignImpl.java

├── controller/

│ └── RoleController.java

├── service/

│ ├── RoleService.java

│ └── impl/

│ └── RoleServiceImpl.java

├── converter/

│ └── RoleConverter.java

└── repo/

├── entity/

│ └── RoleEntity.java

├── mapper/

│ └── RoleMapper.java

└── service/

└── RoleRepoService.java

2. 具体代码示例

API层

package com.epoch.sys.role.api.feign;
import com.epoch.sys.role.api.vo.RoleVO;
import org.springframework.cloud.openfeign.FeignClient;
import org.springframework.web.bind.annotation.*;
@FeignClient(name = "system-service", path = "/api/role")
public interface RoleFeign {
    
    @GetMapping("/{id}")
    RoleVO getRoleById(@PathVariable Long id);
    
    @PostMapping
    RoleVO createRole(@RequestBody CreateRoleDTO createDTO);
}

<JAVA>

package com.epoch.sys.role.api.dto;
import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;
import javax.validation.constraints.NotBlank;
@Data
@Schema(description = "角色创建DTO")
public class CreateRoleDTO {
    
    @NotBlank(message = "角色名称不能为空")
    @Schema(description = "角色名称", required = true)
    private String roleName;
    
    @NotBlank(message = "角色编码不能为空")
    @Schema(description = "角色编码", required = true)
    private String roleCode;
    
    @Schema(description = "角色描述")
    private String description;
}

Feign实现层

<JAVA>

package com.epoch.sys.role.feign.impl;
import com.epoch.sys.role.api.feign.RoleFeign;
import com.epoch.sys.role.api.dto.CreateRoleDTO;
import com.epoch.sys.role.api.vo.RoleVO;
import com.epoch.sys.role.service.RoleService;
import lombok.RequiredArgsConstructor;
import org.springframework.web.bind.annotation.RestController;
@RestController
@RequiredArgsConstructor
public class RoleFeignImpl implements RoleFeign {
    
    private final RoleService roleService;
    @Override
    public RoleVO getRoleById(Long id) {
        return roleService.getRoleById(id);
    }
    @Override
    public RoleVO createRole(CreateRoleDTO createDTO) {
        return roleService.createRole(createDTO);
    }
}

Service层

<JAVA>

package com.epoch.sys.role.service;
import com.epoch.sys.role.api.dto.CreateRoleDTO;
import com.epoch.sys.role.api.vo.RoleVO;
public interface RoleService {
    
    RoleVO createRole(CreateRoleDTO createDTO);
    
    RoleVO getRoleById(Long id);
    
    RoleVO updateRole(Long id, UpdateRoleDTO updateDTO);
    
    Boolean deleteRole(Long id);
}

<JAVA>

package com.epoch.sys.role.service.impl;
import com.epoch.sys.role.service.RoleService;
import com.epoch.sys.role.converter.RoleConverter;
import com.epoch.sys.role.api.dto.CreateRoleDTO;
import com.epoch.sys.role.api.vo.RoleVO;
import com.epoch.sys.role.repo.entity.RoleEntity;
import com.epoch.sys.role.repo.service.RoleRepoService;
import lombok.RequiredArgsConstructor;
import org.springframework.stereotype.Service;
@Service
@RequiredArgsConstructor
public class RoleServiceImpl implements RoleService {
    
    private final RoleRepoService roleRepoService;
    private final RoleConverter roleConverter = RoleConverter.INSTANCE;
    @Override
    public RoleVO createRole(CreateRoleDTO createDTO) {
        RoleEntity roleEntity = roleConverter.toEntity(createDTO);
        boolean saved = roleRepoService.save(roleEntity);
        if (!saved) {
            throw new RuntimeException("创建角色失败");
        }
        return roleConverter.toVO(roleEntity);
    }
    @Override
    public RoleVO getRoleById(Long id) {
        RoleEntity roleEntity = roleRepoService.getById(id);
        return roleConverter.toVO(roleEntity);
    }
}

Converter层

<JAVA>

package com.epoch.sys.role.converter;
import com.epoch.sys.role.api.dto.CreateRoleDTO;
import com.epoch.sys.role.api.vo.RoleVO;
import com.epoch.sys.role.repo.entity.RoleEntity;
import org.mapstruct.Mapper;
import org.mapstruct.factory.Mappers;
@Mapper
public interface RoleConverter {
    
    RoleConverter INSTANCE = Mappers.getMapper(RoleConverter.class);
    RoleEntity toEntity(CreateRoleDTO createDTO);
    
    RoleVO toVO(RoleEntity entity);
}

Repo层

<JAVA>

package com.epoch.sys.role.repo.entity;
import com.baomidou.mybatisplus.annotation.TableName;
import lombok.Data;
@Data
@TableName("sys_role")
public class RoleEntity {
    private Long id;
    private String roleName;
    private String roleCode;
    private String description;
    private Integer status;
    private java.time.LocalDateTime createTime;
    private java.time.LocalDateTime updateTime;
}

包命名检查

• 所有包名均为全小写
• 使用单数名词形式
• 避免使用缩写
• 层次结构符合规范
• 包名准确表达职责

类命名检查

• 使用大驼峰命名法
• 类名准确表达职责
• 接口实现关系正确
• 避免泛化名称
• DTO/VO命名规范

代码质量检查

• 包依赖关系合理
• 类职责单一明确
• 命名语义清晰
• 符合架构规范

📞 执行与维护

执行要求

• 所有新开发项目必须遵守本规范
• 存量项目在重构时逐步迁移至本规范
• 代码审查时严格检查命名规范

维护责任

• 制定部门：架构组
• 执行监督：各项目技术负责人
• 问题反馈：通过技术委员会渠道