命名规范

🏷️ 统一命名：确保代码命名的一致性和可读性

📋 目录

• 实体类命名
• 字段命名规范
• 类和接口命名
• 方法命名
• 包命名
• 数据库命名
• 常量命名

---

实体类命名

业务实体 vs 系统实体

// ✅ 业务实体：继承BaseEntity，以Entity结尾
public class LeaveApplicationEntity extends BaseEntity {
    // 业务实体
}

// ✅ 系统实体：继承SysBaseEntity，以Entity结尾
public class SysUserEntity extends SysBaseEntity {
    // 系统实体
}

实体类命名规则

• 业务实体: XxxEntity (如 ExpenseClaimEntity)
• 系统实体: SysXxxEntity (如 SysMenuEntity)
• 子表实体: XxxDetailEntity (如 OrderDetailEntity)

---

字段命名规范

🔥 核心原则

业务实体字段：全大写无下划线
系统实体字段：驼峰命名

业务实体字段（继承BaseEntity）

@Table("LEAVE_APPLICATION")
public class LeaveApplicationEntity extends BaseEntity {
    
    // ✅ 正确：全大写无下划线
    @Column("LEAVENO")
    @JsonProperty("LEAVENO")
    private String LEAVENO;
    
    @Column("LEAVETITLE")
    @JsonProperty("LEAVETITLE")
    private String LEAVETITLE;
    
    @Column("STARTTIME")
    @JsonProperty("STARTTIME")
    private Date STARTTIME;
    
    @Column("APPLICANTNAME")
    @JsonProperty("APPLICANTNAME")
    private String APPLICANTNAME;
    
    // ❌ 错误示例
    private String leave_no;        // 错误：包含下划线
    private String leaveTitle;      // 错误：驼峰命名
    private String Leave_Title;     // 错误：混合风格
}

系统实体字段（继承SysBaseEntity）

@Table("sys_menu")
public class SysMenuEntity extends SysBaseEntity {
    
    // ✅ 正确：驼峰命名
    private String menuName;
    private String menuUrl;
    private Integer sortOrder;
    private String parentId;
    
    // ❌ 错误示例
    private String MENU_NAME;       // 错误：系统实体不用大写
    private String menu_name;       // 错误：包含下划线
}

BaseEntity已包含字段（全大写）

// 这些字段已在BaseEntity中定义，无需重复声明
ID              // 主键
CREATORTIME     // 创建时间
CREATORUSER     // 创建人ID
LASTMODIFYTIME  // 修改时间
LASTMODIFYUSER  // 修改人ID
DELETETIME      // 删除时间
DELETEUSER      // 删除人ID
ENABLEDMARK     // 有效标志
SORTCODE        // 排序码
ORGANIZE        // 组织ID
FLOWPHASE       // 流程状态
STEPNAME        // 流程环节名称

SysBaseEntity已包含字段（驼峰）

// 这些字段已在SysBaseEntity中定义
id              // 主键
creatorTime     // 创建时间
creatorUser     // 创建人
lastModifyTime  // 修改时间
lastModifyUser  // 修改人
enabledMark     // 有效标志

---

类和接口命名

Controller命名

// ✅ 正确：XxxController
public class LeaveApplicationController { }
public class ExpenseClaimController { }

// ❌ 错误：不要加Basic等后缀
public class LeaveApplicationBasicController { }  // 错误

Service命名

// 接口：XxxService
public interface LeaveApplicationService { }

// 实现：XxxServiceImpl
public class LeaveApplicationServiceImpl implements LeaveApplicationService { }

// ❌ 错误
public class LeaveApplicationServiceImplement { }  // 应该是Impl
public class LeaveApplicationBasicService { }      // 不要加Basic

Mapper命名

// ✅ 正确：XxxMapper
@Mapper
public interface LeaveApplicationMapper extends BasicMapper<LeaveApplicationEntity> { }

// ❌ 错误
public interface LeaveApplicationDao { }           // 应该用Mapper
public interface LeaveApplicationRepository { }    // 应该用Mapper

DTO/VO命名

// 数据传输对象
public class UserDTO { }           // Data Transfer Object
public class UserCreateDTO { }     // 创建用户DTO
public class UserUpdateDTO { }     // 更新用户DTO

// 视图对象
public class UserVO { }            // View Object
public class UserListVO { }        // 列表视图
public class UserDetailVO { }      // 详情视图

// 查询对象
public class UserQuery { }         // 查询条件
public class UserSearchParam { }   // 搜索参数

---

方法命名

基本规范

// 查询方法
getXxx()        // 获取单个对象
listXxx()       // 获取列表
findXxx()       // 查找
queryXxx()      // 查询
searchXxx()     // 搜索

// 操作方法
createXxx()     // 创建
saveXxx()       // 保存
updateXxx()     // 更新
deleteXxx()     // 删除
removeXxx()     // 移除

// 判断方法
isXxx()         // 是否
hasXxx()        // 是否有
canXxx()        // 能否
checkXxx()      // 检查
validateXxx()   // 验证

// 转换方法
toXxx()         // 转换为
parseXxx()      // 解析
formatXxx()     // 格式化
convertXxx()    // 转换

Service方法命名

public interface BusinessService {
    // 基础CRUD
    List<Entity> getList(QueryBuilder pagination);
    Entity getInfo(String id);
    void create(Entity entity);
    void update(String id, Entity entity);
    void delete(String id);
    
    // 业务方法
    void submitApproval(String id);
    void approveRequest(String id, ApprovalDTO dto);
    List<Entity> getMyTasks();
    Map<String, Object> getStatistics(Date startDate, Date endDate);
    
    // 批量操作
    void batchDelete(List<String> ids);
    void batchImport(List<Entity> entities);
}

钩子方法命名（BasicService）

// 数据操作钩子
beforeSave()         // 保存前
afterSave()          // 保存后
beforeDelete()       // 删除前
afterDelete()        // 删除后

// 子表操作钩子
beforeSaveSubTable() // 子表保存前
afterSaveSubTable()  // 子表保存后

// 流程钩子
beforeTaskExec()     // 任务执行前
afterTaskExec()      // 任务执行后
onFlowEnd()         // 流程结束时
flowResurgence()    // 流程复活

// 数据获取钩子
afterGetData()      // 获取数据后

---

包命名

基础包结构

jpwise.extend                    // 业务扩展模块
jpwise.extend.controller         // 控制器
jpwise.extend.service            // 服务接口
jpwise.extend.service.impl       // 服务实现
jpwise.extend.base.entity        // 实体类
jpwise.extend.base.mapper        // Mapper接口
jpwise.extend.model              // 模型类（DTO/VO）
jpwise.extend.constant           // 常量类
jpwise.extend.enums             // 枚举类

模块命名

jpwise-admin        // 主应用模块
jpwise-common       // 公共模块
jpwise-system       // 系统模块
jpwise-workflow     // 工作流模块
jpwise-extend       // 扩展模块
jpwise-file         // 文件模块

---

数据库命名

表命名

-- 业务表：大写下划线
LEAVE_APPLICATION       -- 请假申请表
EXPENSE_CLAIM          -- 费用报销表
PURCHASE_ORDER         -- 采购订单表

-- 系统表：小写下划线
sys_user               -- 用户表
sys_menu               -- 菜单表
sys_role               -- 角色表

-- 关联表：表1_表2
user_role              -- 用户角色关联
role_menu              -- 角色菜单关联

字段命名

-- 业务表字段：大写无下划线（与实体字段对应）
CREATE TABLE LEAVE_APPLICATION (
    ID VARCHAR(50),
    LEAVENO VARCHAR(50),
    LEAVETITLE VARCHAR(200),
    STARTTIME DATETIME,
    ENDTIME DATETIME,
    CREATORUSER VARCHAR(50),
    CREATORTIME DATETIME
);

-- 系统表字段：小写下划线
CREATE TABLE sys_user (
    id VARCHAR(50),
    user_name VARCHAR(50),
    real_name VARCHAR(50),
    create_time DATETIME
);

---

常量命名

常量类

public class StatusConstant {
    // 全大写下划线分隔
    public static final String DRAFT = "DRAFT";
    public static final String PENDING_APPROVAL = "PENDING_APPROVAL";
    public static final String APPROVED = "APPROVED";
    public static final String REJECTED = "REJECTED";
    
    // 数值常量
    public static final int MAX_RETRY_COUNT = 3;
    public static final long CACHE_TIMEOUT = 3600L;
}

枚举命名

// 枚举类名：XxxEnum
public enum ApprovalStatusEnum {
    // 枚举值：全大写下划线
    DRAFT("DRAFT", "草稿"),
    PENDING("PENDING", "待审批"),
    APPROVED("APPROVED", "已通过"),
    REJECTED("REJECTED", "已拒绝");
    
    private String code;
    private String name;
    
    ApprovalStatusEnum(String code, String name) {
        this.code = code;
        this.name = name;
    }
}

配置键命名

# application.yml中的配置键
jpwise.file.upload-path=/uploads
jpwise.cache.timeout=3600
jpwise.workflow.enabled=true

---

URL路径命名

RESTful API路径

// 基础路径：/api/模块/资源
@RequestMapping("/api/extend/LeaveApplication")
@RequestMapping("/api/system/User")
@RequestMapping("/api/workflow/Task")

// 操作路径
GET    /api/extend/LeaveApplication          // 列表
GET    /api/extend/LeaveApplication/{id}     // 详情
POST   /api/extend/LeaveApplication          // 创建
POST   /api/extend/LeaveApplication/update/{id}  // 更新
POST   /api/extend/LeaveApplication/{id}     // 删除

// 批量操作
POST   /api/extend/LeaveApplication/Actions/Import
POST   /api/extend/LeaveApplication/Actions/Export

---

命名检查清单

实体类检查

• [ ] 业务实体继承BaseEntity
• [ ] 系统实体继承SysBaseEntity
• [ ] 业务实体字段全大写无下划线
• [ ] 系统实体字段驼峰命名
• [ ] 类名以Entity结尾

服务类检查

• [ ] Controller命名规范
• [ ] Service接口和实现命名规范
• [ ] Mapper接口命名规范
• [ ] 不包含Basic等冗余后缀

数据库检查

• [ ] 业务表大写下划线
• [ ] 系统表小写下划线
• [ ] 字段命名与实体对应

方法检查

• [ ] 方法名表达清晰意图
• [ ] 布尔方法以is/has/can开头
• [ ] 遵循动词+名词模式

---

常见命名错误

// ❌ 错误示例集合

// 1. 字段命名错误
private String user_name;      // 业务实体应该用USERNAME
private String userName;       // 业务实体应该用USERNAME
private String USERNAME;       // 系统实体应该用userName

// 2. 类命名错误
public class UserBasicController { }     // 不要加Basic
public class UserCtrl { }               // 不要缩写
public class UserServiceImplementation { } // 应该是Impl

// 3. 方法命名错误
public void do() { }                    // 太模糊
public void processUserDataAndSave() { } // 太长
public void proc() { }                  // 不要缩写

// 4. 常量命名错误
public static final String draft = "DRAFT";  // 应该大写
public static final String DRAFT-STATUS = "DRAFT"; // 不能用连字符

---

💡 提示：良好的命名是代码可读性的基础。始终记住：业务实体字段全大写，系统实体字段驼峰，这是JPwise项目的核心命名规范。