后端功能开发
校对日期:2026-11-16。适用于社区版及全部商业版。
在后端增加一个自己的功能,要写一张表和一组固定的文件:实体类、Mapper、Service、Controller,需要在网站前台显示时再加公开接口和模板标签。 本文以源码自带的示例功能(Example)为例说明每个文件写什么;后台界面一侧的开发见后台界面开发, 包和分层的总体说明见源码结构与分层。
一、示例功能
com. 包里的 Example(示例)是专门留给二次开发参考的一套最小功能:一张表 ujcms_example (名称、描述、身高、出生日期、是否启用),带齐了从表到界面的全部文件。下表的路径都在 ujcms-cms/ 之下:
| 层 | 文件 | 是否必需 |
|---|---|---|
| 表结构 | resources/ 里的 ujcms_example | 是 |
| 实体类 | java/、java/ | 是 |
| Mapper | java/、resources/ | 是 |
| 查询参数 | java/ | 是 |
| Service | java/ | 是 |
| 后台接口 | java/ | 是 |
| 公开接口 | java/ | 前台要用接口取数据、提交数据时 |
| 模板标签 | java/ 下的 ExampleDirective.、ExampleListDirective.、ExamplePageDirective. | 模板里要取数据时 |
| 前台页面 | java/,模板为默认主题 templates/ 下的 sys_、sys_、sys_ | 要有独立的前台页面时 |
示例功能默认是停用的:三个 Controller 类上的注解被注释掉了,所以没有任何接口和页面对外开放;表、Service 和三个模板标签是生效的。 想让它运行起来看效果,把三个类开头被注释的注解恢复,并补上因此缺少的 import:
// web/backendapi/ExampleController.java
@RestController("backendExampleController")
@RequestMapping(BACKEND_API + "/ext/example")
// web/api/ExampleController.java
@Tag(name = "ExampleController", description = "示例接口")
@RestController
@RequestMapping({API + "/example", FRONTEND_API + "/example"})
// web/frontend/ExampleController.java
@FrontendController("frontendExampleController")同样结构、正在使用的功能可以看标签管理(内容 → 标签管理):把上表路径里的 ext 换成 core、Example 换成 Tag 基本就是它的文件。 它比示例多了“数据属于某个站点”的处理,“后台接口”一节会用到。
增加自己的功能时,把这组文件按同样的位置和命名各写一份。源码中不再有代码生成器,这些文件都是手写的,通常的做法是复制示例功能的文件再改。
二、建表
在变更日志里写建表的变更集,启动程序后表自动创建。命名和类型的约定、变更日志的写法见数据库设计规范与表结构变更。
三、实体类与 Mapper
每张表有两个实体类和一对 Mapper 文件(各部分的写法详见实体类与 Mapper):
GeneratedExample:与表字段一一对应,一个字段一个属性,带校验注解(@NotNull、@Length)和默认值,另有常量TABLE_(去掉NAME = "example" ujcms_前缀的表名,查询时使用)。Example:继承GeneratedExample。关联对象、常量、计算属性都写在这个类里,示例功能没有这些内容,所以是空的。ExampleMapper:insert、update、delete、select、selectAll五个方法。ExampleMapper.:字段映射和上述五个方法的 SQL。xml selectAll引用公用的查询片段,支持任意条件和排序。
四、Service 与查询参数
Service 是普通的 Spring Bean,用构造方法注入 Mapper。ExampleService 的主要部分:
@Service
public class ExampleService {
private final ExampleMapper mapper;
private final SnowflakeSequence snowflakeSequence;
@Transactional(rollbackFor = Exception.class)
public void insert(Example bean) {
bean.setId(snowflakeSequence.nextId());
mapper.insert(bean);
}
public List<Example> selectList(ExampleArgs args) {
QueryInfo queryInfo = QueryParser.parse(args.getQueryMap(), GeneratedExample.TABLE_NAME, "id_desc");
return mapper.selectAll(queryInfo);
}
public Page<Example> selectPage(ExampleArgs args, int page, int pageSize) {
return PageMethod.startPage(page, pageSize).doSelectPage(() -> selectList(args));
}
}主键在
insert里用snowflakeSequence.生成,见主键生成。nextId() 写操作加
@Transactional(rollbackFor = Exception.。class) 列表查询只有一个
selectList:查询条件放在一个 Map 里(如Contains_name→abc),QueryParser.把它解析成表关联、 条件和排序,第三个参数是默认排序。分页由 PageHelper 完成,parse selectPage和按offset、limit取数的重载都调用selectList。ExampleArgs继承com.,把常用的条件包装成方法,免得调用方记条件的写法:ujcms. common. query. BaseQueryArgs javapublic ExampleArgs name(@Nullable String name) { if (StringUtils.isNoneBlank(name)) { queryMap.put("Contains_name", name); } return this; }
查询条件的完整写法(比较符、关联表、分组、排序)见查询解析器 QueryParser。
五、后台接口
后台接口的 Controller 放在 web.backendapi 包,地址是 /api/,功能名用小写加连字符(如 message-board)。 ExampleController 的列表和修改两个方法:
@RestController("backendExampleController")
@RequestMapping(BACKEND_API + "/ext/example")
public class ExampleController {
@GetMapping
@PreAuthorize("hasAnyAuthority('example:list','*')")
public Page<Example> list(@RequestParam("page") Integer page, @RequestParam("pageSize") Integer pageSize,
HttpServletRequest request) {
ExampleArgs args = ExampleArgs.of(getQueryMap(request.getQueryString()));
return springPage(service.selectPage(args, validPage(page), validPageSize(pageSize)));
}
@PutMapping
@PreAuthorize("hasAnyAuthority('example:update','*')")
@OperationLog(module = "example", operation = "update", type = OperationType.UPDATE)
public ResponseEntity<Body> update(@RequestBody @Valid Example bean) {
Example example = service.select(bean.getId());
if (example == null) {
throw new Http404Exception("Example not found. ID = " + bean.getId());
}
Entities.copy(bean, example);
service.update(example);
return Responses.ok();
}
}要点:
- Bean 名称。 后台接口和公开接口的 Controller 类名相同,后台的写成
@RestController("backendExampleController")加以区分。 - 五个标准方法。
GET(分页列表)、GET {id}(单条)、POST(新增)、PUT(修改)、DELETE(按 ID 列表删除), 后台界面的通用表单组件按这五个接口工作。 - 权限。 每个方法都要有
@PreAuthorize("hasAnyAuthority('<资源>:,漏写的方法会被拒绝访问(403)。 五个方法的权限码依次是<操作>', '*')") example:list、example:show、example:create、example:update、example:delete; 其它动作自己取名,如article:reject。权限码还要登记到后台界面的权限树里,否则除了拥有全部功能权限的角色,谁也得不到它。 - 查询条件。
getQueryMap(request.取出地址里所有以getQueryString()) Q_开头的参数作为查询条件,如?Q_Contains_,所以列表方法不用为每个查询项声明参数。name= abc&Q_ OrderBy= id_ desc - 分页。
validPage、validPageSize规范页码和每页条数(每页最多 1000 条);springPage把结果转换成统一的分页结构, 返回的 JSON 里数据在content,总数在page.。totalElements - 保存。 不直接保存请求体反序列化出来的对象:修改时先查出原对象,再用
Entities.把请求里的值拷贝过去; 不允许客户端修改的属性,在后面的参数里列出来排除。字段的长度、非空校验由copy(bean, example) @Valid和实体类上的注解完成。 - 返回。 增、删、改成功返回
Responses.ok();找不到数据抛Http404Exception。Long类型在 JSON 里一律输出为字符串 (JavaScript 的数字装不下雪花算法的主键),所以界面拿到的 ID 是字符串。 - 操作日志。
@OperationLog把这次操作记入操作日志,module和operation是日志里显示的模块和动作的代号, 它们的中文名称在后台界面里登记。操作日志的查询界面(日志 → 操作日志)是商业版基础版的功能。
数据属于某个站点时(表里有 site_id_),还要做三件事,写法见 com.:
// 列表:只查当前站点的数据
TagArgs args = TagArgs.of(getQueryMap(request.getQueryString())).siteId(Contexts.getCurrentSiteId());
// 新增:站点、创建人由服务端填写,不接受请求里的值
Entities.copy(bean, tag, "siteId", "userId", "created", "refers");
tag.setSiteId(site.getId());
tag.setUserId(user.getId());
// 修改、删除:先确认这条数据属于当前站点
ValidUtils.dataInSite(tag.getSiteId(), site.getId());当前站点(Contexts.)是管理员在后台界面右上角选中的那个站点,当前用户用 Contexts. 取得。
六、公开接口、模板标签与前台页面
只在后台管理的数据不需要这一节的内容。
公开接口(
web.)同时映射到api. ExampleController /api/example和/frontend/。它面向匿名访客,与后台接口有三点不同: 查询条件用example QueryUtils.取,这个方法不允许访客用敏感字段或关联用户等表来查询; 接收访客提交的数据时用验证码防刷(getPublicQueryMap(params) CaptchaGuard,见验证码); 类上加@Tag、方法上加@Operation(summary = …),作为接口文档里的分组名和接口标题。模板标签 实现 FreeMarker 的
TemplateDirectiveModel:读取标签参数,调用 Service,把结果放进返回变量。写好后要在配置类里登记名称, 示例的三个标签登记在com.:ujcms. cms. ext. ContextConfig javaconfiguration.setSharedVariable("ExampleList", new ExampleListDirective(exampleService));模板里即可使用
[@ExampleList name=;分页标签'abc' limit= '10'; list]…[/ @ExampleList] [@ExamplePage]的用法见默认主题的templates/。sys_ example. html limit、page等通用参数见 模板标签与 API 的通用参数。前台页面 的 Controller 用
@FrontendController标注,方法声明Site site参数,返回site., 即当前站点主题里的assembleTemplate("sys_ example") sys_。路由只写不带站点子目录的地址(example. html /example),不要自己写子目录前缀。 模板的写法见模板编写。
七、检查
- 启动程序,用后台界面或接口工具调用新接口。后台接口要带登录后得到的令牌(请求头
Authorization: Bearer <令牌>)。 - 执行
./mvnw test。其中BackendControllerGuardTest检查每个后台接口方法都声明了@PreAuthorize,FrontendControllerGuardTest检查前台页面的 Controller 用了@FrontendController且没有手写子目录路由,MessageBundleParityTest检查messages.与properties messages_的条目一致。en. properties