project-conventions

项目编码规范指南，遵循阿里巴巴Java开发手册，确保代码风格统一

Zur Installation springen

Repository: wujun728/jun_java_plugin
Letzte Quellaktivität: 22. Mai 2026 um 08:51
Erkannte Sprache von SKILL.md: Chinesisch
Sterne: 239
Forks: 72

Installationsoptionen

Standardmäßig ist der Prompt ausgewählt, der zuerst die Quelle prüft. Sie können zu einem direkten Befehl wechseln oder eine lokale Kopie herunterladen.

Quelldateien prüfen

Lesen Sie SKILL.md und alle von SkillsMP angezeigten Begleitdateien, bevor Sie sich für eine Installation entscheiden.

Zurück zur Suche Zurück zur Installation

name	project-conventions
description	项目编码规范指南，遵循阿里巴巴Java开发手册，确保代码风格统一

project-conventions - 项目编码规范

本规范基于《阿里巴巴Java开发手册》，结合项目实际情况制定，适用于本项目所有Java代码开发。

一、项目结构规范

1.1 包结构

net.trueland.tshop.retail.system.center
├── domain/                      # 领域层
│   ├── entity/                  # 数据库实体类
│   ├── dao/                     # MyBatis Mapper接口
│   └── pojo/                    # 数据传输对象
│       └── {模块名}/            # 按功能模块分包
│           ├── {实体}DTO.java   # 数据传输对象
│           ├── {实体}VO.java    # 视图对象
│           └── {实体}SearchQO.java  # 查询对象
├── mapping/                     # MapStruct映射器
│   └── {模块名}/
├── repository/                  # 仓储层
│   └── {模块名}/
├── service/                     # 业务逻辑层
│   └── {模块名}/
├── web/                         # 控制器层
│   ├── admin/                   # 管理端API
│   ├── tenant/                  # 租户端API
│   ├── app/                     # C端API
│   └── feign/                   # Feign接口
├── client/                      # 第三方服务客户端
│   ├── feign/                   # Feign客户端
│   ├── retrofit/                # Retrofit客户端
│   ├── config/                  # 客户端配置
│   └── model/                   # 客户端模型
├── common/                      # 公共模块
│   ├── constants/               # 常量类
│   ├── enums/                   # 枚举类
│   ├── utils/                   # 工具类
│   └── ErrorCode.java           # 错误码
├── aspect/                      # AOP切面
├── annotation/                  # 自定义注解
├── manager/                     # 管理器
└── config/                      # 配置类

1.2 资源文件结构

src/main/resources/
├── mybatis/
│   └── mapper/                  # MyBatis XML映射文件
│       └── {实体名}Dao.xml
├── application.yml              # 主配置文件
├── application-{env}.yml        # 环境配置文件
└── bootstrap.yml                # 启动配置文件

二、命名规范

2.1 包命名

格式：全部小写，使用点分隔
规则：反向域名 + 项目名 + 模块名
示例：net.trueland.tshop.retail.system.center.service.application

2.2 类命名

类型	命名格式	示例
Entity（实体类）	`{功能名}`	`Application`, `OrgUser`
DAO（数据访问）	`{功能名}Dao`	`ApplicationDao`, `OrgUserDao`
Repository（仓储）	`{功能名}Repository`	`ApplicationRepository`
Service（服务）	`{功能名}Service`	`ApplicationService`
Controller（控制器）	`{功能名}Controller`	`ApplicationController`
Mapper（对象映射）	`{功能名}Mapper`	`ApplicationMapper`
DTO（传输对象）	`{功能名}DTO`	`ApplicationDTO`
VO（视图对象）	`{功能名}VO`	`ApplicationVO`
QO（查询对象）	`{功能名}SearchQO`	`ApplicationSearchQO`
Enum（枚举）	`{功能名}Enum`	`EnableEnum`, `StatusEnum`
Constants（常量）	`{功能名}Constants`	`SystemConstants`
Utils（工具）	`{功能名}Utils`	`DateUtils`, `StringUtils`
Config（配置）	`{功能名}Config`	`WebConfig`, `RedisConfig`
Aspect（切面）	`{功能名}Aspect`	`LogAspect`

操作类型	命名前缀	示例
查询单个	`get`, `find`, `query`	`getById()`, `findByName()`
查询列表	`list`, `select`	`listByQo()`, `selectAll()`
新增	`add`, `insert`, `create`	`add()`, `insertSelective()`
修改	`update`, `modify`, `edit`	`update()`, `updateById()`
删除	`delete`, `remove`	`deleteById()`, `removeByIds()`
判断存在	`exist`, `check`, `is`	`exist()`, `checkExists()`
统计	`count`	`countByStatus()`

数据库类型	Java类型	说明
BIGINT	Long	主键、ID类型
INT/TINYINT	Integer	状态、计数
VARCHAR	String	字符串
DATETIME/TIMESTAMP	LocalDateTime	时间类型
DECIMAL	BigDecimal	金额类型
TEXT	String	长文本

Controller层（Web层）
    ↓ 调用
Service层（业务逻辑层）
    ↓ 调用
Repository层（数据仓储层）
    ↓ 调用
DAO层（数据访问层）
    ↓ 操作
Database（数据库）

@Api(tags = "应用管理")
@RestController
@RequiredArgsConstructor
@RequestMapping("/application")
public class ApplicationController {

    private final ApplicationService applicationService;

    @PostMapping("/add")
    @ApiOperation(value = "新增应用")
    public ApiResult<Long> add(@Validated @RequestBody ApplicationDTO dto) {
        return ApiResult.ok(applicationService.add(dto));
    }
}

@Service
@AllArgsConstructor
@Slf4j
public class ApplicationService {

    private final ApplicationMapper applicationMapper;
    private final ApplicationRepository applicationRepository;

    public Long add(ApplicationDTO dto) {
        Application entity = applicationMapper.toEntity(dto);
        applicationRepository.addEntity(entity);
        return entity.getId();
    }

    @Transactional(rollbackFor = Exception.class)
    public void batchUpdate(List<ApplicationDTO> dtoList) {
        // 事务操作
    }
}

@Repository
@RequiredArgsConstructor
public class ApplicationRepository {

    private final ApplicationDao applicationDao;

    public void addEntity(Application row) {
        applicationDao.insertSelective(row);
    }

    public Application exist(Long id) {
        Application data = applicationDao.selectByPrimaryKey(id);
        if (Objects.isNull(data)) {
            throw new ServiceException(ErrorCode.DATA_NOT_EXISTS);
        }
        return data;
    }

    public Application getById(Long id) {
        return applicationDao.selectByPrimaryKey(id);
    }
}

@Mapper
public interface ApplicationDao {

    int insert(Application row);

    int insertSelective(Application row);

    Application selectByPrimaryKey(Long id);

    int updateByPrimaryKeySelective(Application row);

    int deleteByPrimaryKey(Long id);

    List<Application> selectByQo(@Param(value = "qo") ApplicationSearchQO qo);
}

// Controller
@Api(tags = "模块描述")
@RestController
@RequiredArgsConstructor
@RequestMapping("/path")

// Service
@Service
@AllArgsConstructor
@Slf4j

// Repository
@Repository
@RequiredArgsConstructor

// DAO
@Mapper

// Entity/DTO/VO
@Data

// 配置类
@Configuration

// 切面
@Aspect
@Component

// Controller方法
@PostMapping("/add")
@ApiOperation(value = "操作描述")

// 事务控制
@Transactional(rollbackFor = Exception.class)

// 异常处理
@SneakyThrows

// 文档注解
@ApiModelProperty("字段描述")

// 验证注解
@NotNull(message = "xxx不能为空")
@NotEmpty(message = "xxx不能为空")
@NotBlank(message = "xxx不能为空")
@Size(max = 100, message = "xxx长度不能超过100")

// MyBatis参数
@Param(value = "paramName")

@Mapper(componentModel = "spring")
public interface ApplicationMapper {

    Application toEntity(ApplicationDTO dto);

    void updateEntity(ApplicationDTO dto, @MappingTarget Application entity);

    ApplicationVO toVO(Application entity);

    List<ApplicationVO> toVOList(List<Application> list);

    @Mapping(target = "targetField", source = "sourceField")
    SomeVO customMapping(SomeEntity entity);
}

/**
 * 类功能描述
 *
 * @author 作者名
 */
public class ClassName {
}

/**
 * 方法功能描述
 *
 * @param paramName 参数说明
 * @return 返回值说明
 */
public ReturnType methodName(ParamType paramName) {
}

/**
 * 字段描述（可选）
 */
@ApiModelProperty("字段描述")
private String fieldName;

// 单行注释，说明下一行代码的作用
doSomething();

/*
 * 多行注释
 * 说明复杂逻辑
 */

@Getter
@AllArgsConstructor
public enum ErrorCode implements IRespCode {

    // 通用错误码 10000-10999
    SYSTEM_ERROR(10000, HttpStatus.INTERNAL_SERVER_ERROR, "系统错误"),
    PARAM_ERROR(10001, HttpStatus.BAD_REQUEST, "参数错误"),
    DATA_NOT_EXISTS(10002, HttpStatus.OK, "数据不存在"),

    // 业务错误码 11000-11999
    APPLICATION_NOT_EXISTS(11000, HttpStatus.OK, "应用不存在"),
    APPLICATION_NAME_EXISTS(11001, HttpStatus.OK, "应用名称已存在"),
    ;

    private final Integer code;
    private final HttpStatus httpStatus;
    private final String message;
}

// Repository层抛出业务异常
public Application exist(Long id) {
    Application data = applicationDao.selectByPrimaryKey(id);
    if (Objects.isNull(data)) {
        throw new ServiceException(ErrorCode.DATA_NOT_EXISTS);
    }
    return data;
}

// Service层抛出业务异常
public void add(ApplicationDTO dto) {
    if (checkNameExists(dto.getName())) {
        throw new ServiceException(ErrorCode.APPLICATION_NAME_EXISTS);
    }
    // ...
}

// 成功响应
return ApiResult.ok(data);
return ApiResult.ok();

// 失败响应
return ApiResult.err(ErrorCode.PARAM_ERROR);
return ApiResult.err(code, message);

import cn.hutool.core.util.ObjectUtil;

// 判空
ObjectUtil.isNull(obj)
ObjectUtil.isNotNull(obj)
ObjectUtil.isEmpty(collection)
ObjectUtil.isNotEmpty(collection)

// 相等判断
ObjectUtil.equal(obj1, obj2)

import org.apache.commons.lang3.StringUtils;

// 判空
StringUtils.isEmpty(str)
StringUtils.isNotEmpty(str)
StringUtils.isBlank(str)
StringUtils.isNotBlank(str)

import cn.hutool.core.collection.CollUtil;

// 判空
CollUtil.isEmpty(list)
CollUtil.isNotEmpty(list)

// 转换
CollUtil.newArrayList(items)

import com.alibaba.fastjson.JSON;

// 序列化
String json = JSON.toJSONString(obj);

// 反序列化
Object obj = JSON.parseObject(json, Class.class);
List<T> list = JSON.parseArray(json, Class.class);

@Slf4j
public class ApplicationService {

    public void process() {
        log.info("开始处理应用, applicationId: {}", applicationId);

        try {
            // 业务逻辑
            log.debug("处理详情: {}", details);
        } catch (Exception e) {
            log.error("处理应用失败, applicationId: {}, error: {}", applicationId, e.getMessage(), e);
            throw new ServiceException(ErrorCode.SYSTEM_ERROR);
        }

        log.info("应用处理完成, applicationId: {}", applicationId);
    }
}

场景	Java类型	说明
主键ID	Long	64位整数
状态/类型	Integer	使用枚举值
布尔值	Integer	0/1表示
时间	LocalDateTime	不使用Date
金额	Long	以分为单位
精确计算	BigDecimal	财务计算
字符串	String	-
集合	List	优先使用List

// 推荐：构造函数注入
@RequiredArgsConstructor
public class ApplicationService {
    private final ApplicationRepository applicationRepository;
}

// 不推荐：字段注入
@Autowired
private ApplicationRepository applicationRepository;

// 推荐
if (Objects.isNull(obj)) { }
if (ObjectUtil.isEmpty(list)) { }

// 不推荐
if (obj == null) { }
if (list == null || list.size() == 0) { }

// 查询可能为空的数据
public Optional<Application> findById(Long id) {
    return Optional.ofNullable(applicationDao.selectByPrimaryKey(id));
}

// 使用
applicationService.findById(id)
    .orElseThrow(() -> new ServiceException(ErrorCode.DATA_NOT_EXISTS));

// 集合转换
List<Long> ids = list.stream()
    .map(Application::getId)
    .collect(Collectors.toList());

// 过滤
List<Application> filtered = list.stream()
    .filter(app -> Objects.equals(app.getStatus(), 1))
    .collect(Collectors.toList());

// 分组
Map<Integer, List<Application>> grouped = list.stream()
    .collect(Collectors.groupingBy(Application::getType));

类别	技术	版本
基础框架	Spring Boot	2.4.2 / 2.6.13
微服务	Spring Cloud	-
ORM框架	MyBatis	-
对象映射	MapStruct	-
工具库	Lombok	-
工具库	Hutool	-
JSON处理	FastJSON	-
API文档	Swagger/Knife4j	-
数据库	MySQL	5.7/8.0
缓存	Redis	-