本文是 Nebula 开发规范的「速查手册」，涵盖框架基类速查、命名约定、REST 接口设计、方法命名约定四大核心速查表。
刚接触 Nebula 框架的开发者，建议先读本文建立整体认知，再深入各专题规范。

---

目录

• 一、框架基类速查表
• 二、命名规范速查
• 三、REST 接口设计规范
• 四、方法命名约定
• 五、核心分层原则

---

一、框架基类速查表

Nebula 对常用能力做了统一封装，开发时应优先使用框架提供的基类与工具，禁止绕过框架直接调用底层开源 API。

基类 / 工具	模块	用途
BaseEntity	nebula-framework-mybatis	实体基类，含 11 个公共字段（id / tenantId / creator / createTime 等）及自动填充
BaseMapper<T>	nebula-framework-mybatis	Mapper 基类，开箱即用单表 CRUD
BaseService<T>	nebula-framework-mybatis	Service 接口基类
BaseServiceImpl<M, T>	nebula-framework-mybatis	Service 实现基类，含 getByIdOrThrow
PageParam	nebula-framework-core	分页入参：pageNo（默认 1）、pageSize（默认 10）、sorts
PageResult<T>	nebula-framework-core	分页响应：total、records、convert() 批量转换
R<T>	nebula-framework-core	HTTP 响应包装：R.ok(data) / R.ok()
BusinessException	nebula-framework-core	业务异常，含错误码和提示
SystemException	nebula-framework-core	系统级异常（IO / 外部调用失败），区别于业务异常
GlobalErrorCode	nebula-framework-core	错误码：PARAM_INVALID、DATA_NOT_FOUND 等
BaseMapperConfig	nebula-framework-core	MapStruct 全局配置（忽略未映射字段）
JsonUtils	nebula-framework-core	JSON 工具，禁止 new ObjectMapper()，统一用此类
NebulaLockHelper	nebula-boot-starter-redis	分布式锁，禁止 StringRedisTemplate.setIfAbsent
NebulaCacheHelper	nebula-boot-starter-redis	Redis 缓存工具，封装 Key 前缀 / JSON / Hash / Set / 过期，禁止直接用 StringRedisTemplate
StreamUtils	spring-core	文件流复制，用 StreamUtils.copy(in, out) 替代手动 byte[] 循环

---

二、命名规范速查

2.1 后端命名

层次	规则	示例
数据库表	t_{业务名蛇形}	t_demo
实体类	{业务名}DO	DemoDO
Mapper 接口	{业务名}Mapper	DemoMapper
动态查询类	{业务名}MapperExt	DemoMapperExt
Service 接口	I{业务名}Service	IDemoService
Service 实现	{业务名}ServiceImpl	DemoServiceImpl
Controller	{业务名}Controller	DemoController
分页入参 VO	{业务名}PageParamVO	DemoPageParamVO
新增/修改入参	{业务名}SaveParamVO	DemoSaveParamVO
列表响应 VO	{业务名}RespVO	DemoRespVO
详情响应 VO	{业务名}DetailVO	DemoDetailVO
对象转换	{业务名}Convert	DemoConvert

2.2 包结构约定

com.huida.nebula.{业务域}.{模块名}/
├── controller/
│   └── {业务名}Controller.java
├── service/
│   ├── I{业务名}Service.java
│   └── impl/
│       └── {业务名}ServiceImpl.java    ← 实现类必须在 impl/ 子目录
├── mapper/
│   ├── {业务名}Mapper.java             ← 固定 SQL / 基础 CRUD
│   └── {业务名}MapperExt.java          ← 动态查询（LambdaQueryWrapper）
├── entity/
│   └── {业务名}DO.java
├── vo/
│   ├── param/
│   │   ├── {业务名}PageParamVO.java
│   │   └── {业务名}SaveParamVO.java
│   └── resp/
│       ├── {业务名}RespVO.java
│       └── {业务名}DetailVO.java
└── convert/
    └── {业务名}Convert.java

注意： Service 实现类（含 SPI 实现）必须放在 service/impl/ 目录，不能与接口文件平级。

---

三、REST 接口设计规范

3.1 标准接口模式

HTTP 方法	路径	说明	入参	响应
POST	/{域}/{资源}/page	分页查询	@RequestBody XxxPageParamVO	R<PageResult<XxxRespVO>>
GET	/{域}/{资源}/{id}	查询详情	@PathVariable Long id	R<XxxDetailVO>
POST	/{域}/{资源}	新增	@Valid @RequestBody XxxSaveParamVO	R<Long>（返回新 id）
PUT	/{域}/{资源}	修改	@Validated(UpdateGroup.class) @RequestBody	R<Void>
DELETE	/{域}/{资源}	批量逻辑删除	@RequestBody List<Long> ids	R<Void>
PATCH	/{域}/{资源}/{id}/v	启用	@PathVariable Long id	R<Void>
PATCH	/{域}/{资源}/{id}/x	禁用	@PathVariable Long id	R<Void>

路径前缀约定： /{业务域}/{资源名}，例如 /system/user、/auth/account

3.2 关键约束

• 返回类型必须为 R<T>，不允许直接返回裸对象
• Controller 中不处理异常，由全局异常处理器统一响应
• Controller 中不写 if 业务判断，不直接处理文件流或设置响应头

---

四、方法命名约定

操作	Service 方法名	Controller 方法名
分页查询	page{业务名}	page{业务名}
详情查询	get{业务名}ById	get{业务名}ById
新增	create{业务名}	create{业务名}
修改	update{业务名}	update{业务名}
逻辑删除	delete{业务名}	delete{业务名}
启用	enable{业务名}	enable{业务名}
禁用	disable{业务名}	disable{业务名}

---

五、核心分层原则

HTTP 请求
    │
    ▼
Controller 层     ← 接收/校验入参，调用 Service，包装 R<T> 响应；不含任何业务 if 逻辑
    │
    ▼
Service 层        ← 业务逻辑、唯一性校验、事务边界、抛出 BusinessException；不写 LambdaQueryWrapper
    │
   ┌┴──────────────────────┐
   ▼                       ▼
Mapper 接口               MapperExt 类
（固定/注解 SQL）          （动态 LambdaQueryWrapper、分页两段式、唯一性检查）
   │
   ▼
MySQL（Flyway 版本化管理）

各层核心禁止事项一览：

禁止行为	所在层	原因
写 if 业务判断	Controller	违反分层原则
处理文件流/设置响应头	Controller	业务逻辑必须下沉到 Service
注入 HttpServletRequest	Service	违反分层原则
写 LambdaQueryWrapper	Service	应放在 MapperExt
直接返回 DO	Controller	泄露数据库结构
@Select 注解 SQL 缺少租户过滤	Mapper	会查出跨租户数据
new ObjectMapper()	任意层	配置不一致，应用 JsonUtils
StringRedisTemplate.setIfAbsent 加锁	Service	非原子释放，应用 NebulaLockHelper
直接用 StringRedisTemplate 读写 Redis	Service	应用 NebulaCacheHelper
跨模块直接注入其他域的 Mapper	Service	应通过对方 Service 接口

详细规范请参阅各专题文档：后端开发规范、数据库设计规范、框架工具使用规范