源码结构与分层
校对日期:2026-11-16。适用于社区版及全部商业版;
ujcms-commercial模块只在商业版源码中。
本文面向拿到源码、准备做二次开发的 Java / Vue 开发者:源码分哪些模块,后端代码怎样分层、放在哪个包, 一个请求从进入程序到访问数据库经过哪些环节。产品层面的介绍(两种开发模式、运行环境、各版本功能)见 UJCMS 简介,从源码启动的步骤见快速开始的“其它部署方式”一节。
一、模块
| 模块 | 内容 |
|---|---|
ujcms-common | 与 CMS 业务无关的公共代码:查询解析、数据库工具、文件存储、安全、验证码、FreeMarker 与 Lucene 的封装。包名 com. |
ujcms-cms | CMS 的全部核心功能:实体类、Mapper、Service、Controller、模板标签,以及建表用的变更日志。包名 com.ujcms.cms |
ujcms-commercial | 商业版功能,按版本分在 com.(基础版)至 t4(旗舰版)四个包里,每个包自成一套 domain / mapper / service / web。社区版源码没有这个模块,商业版源码只带所购版本及以下的包 |
ujcms-starter | 启动模块:启动类 com.、配置文件 src/,以及 src/main/webapp 下的主题(themes)、后台界面的构建产物(cp)和上传目录(uploads) |
ujcms-ui-console | 后台界面(控制台)的源码,Vue 3 单页应用,构建后输出到 ujcms-starter/ |
ujcms-ui-ssr-vue | 前后端分离的示例站点(Nuxt),只调用公开接口,与后端没有编译依赖 |
Maven 的依赖方向是 ujcms-common ← ujcms-cms ←(ujcms-commercial)← ujcms-starter。后端基于 Spring Boot 3.5 (Jakarta EE,jakarta.* 包名),JDK 17 或 21。
二、后端的分层与包
后端分三层:Controller 接收请求,Service 处理业务,Mapper 访问数据库。
Controller → Service → Mapper 接口 → Mapper XML(SQL) → 数据库ujcms-cms 里有两个结构相同的包:com. 是文章、栏目、用户、站点等核心功能,com. 是留言、评论、投票、链接等扩展功能。以 core 为例:
| 包 | 内容 |
|---|---|
core.domain | 实体类;其下的 generated 包是与表字段一一对应的基类,见实体类与 Mapper |
core.mapper | MyBatis 的 Mapper 接口。对应的 XML 在 src/ |
core.service | Service;其下的 args 包是各功能的查询参数类 |
core. | 后台接口的 Controller |
core.web.api | 公开接口的 Controller |
core. | 前台页面的 Controller(返回模板) |
core. | 模板标签(FreeMarker 指令) |
core. | 拦截器、站点解析等 Web 支持类 |
core.component | 不直接对应某张表的业务组件(验证码、密码、主题安装校验等) |
core.generator、core.lucene | 静态页生成、全文索引 |
core.listener | 删除、发布等事件的监听接口 |
core.security | 登录、令牌、HTML 过滤等安全相关的类 |
core.support | 常量、上下文(Contexts)、配置属性(Props)等 |
core 包下的 SecurityConfig、MyBatisConfig、ContextConfig 等是 Spring 配置类。其它资源文件:
ujcms-cms/:表结构的变更日志,见数据库设计规范与表结构变更。src/ main/ resources/ db/ changelog/ ujcms-cms/、src/ main/ resources/ messages. properties messages_:后端提示信息的中英文文本。en. properties
自己写的代码放在哪里,受两条扫描规则约束:
- 启动类只扫描
com.ujcms.cms及其子包,Controller、Service 等放在这个包之外不会生效。 - Mapper 接口按包扫描(
@MapperScan),已登记的包是com.和ujcms. cms. core. mapper com.。 Mapper 放在别的包时,要在自己的配置类上加ujcms. cms. ext. mapper @MapperScan,写法见com.。ujcms. cms. ext. ContextConfig
三、四类入口
同一个功能最多有四种对外的入口,各在一个包里:
| 入口 | 包 | 地址 | 登录方式 | 给谁用 |
|---|---|---|---|---|
| 后台接口 | web.backendapi | /api/backend/** | 令牌(JWT) | 后台界面 |
| 公开接口 | web.api | /api/** | 令牌(JWT),多数接口不需要登录 | 前后端分离的网站前端、小程序、App |
| 同上 | web.api | /frontend/** | 浏览器会话(session) | 模板页面里的 AJAX 和表单 |
| 前台页面 | web.frontend | /channel/…、/article/… 等 | 浏览器会话 | 访客的浏览器 |
| 模板标签 | web.directive | 无地址,在模板中调用 | — | 主题模板 |
- 公开接口的 Controller 同时映射到
/api和/frontend两个前缀,如@RequestMapping({API + "/。两个前缀的代码相同,区别只在登录方式:tag", FRONTEND_ API + "/ tag"}) /api/**无状态、 不使用会话、不校验 CSRF;/frontend/**使用会话,提交数据要带 CSRF 令牌,见前台表单与 AJAX 的 CSRF 令牌。 前缀常量在com.。ujcms. cms. core. support. UrlConstants - 前台页面的 Controller 用
@FrontendController标注(不是@Controller),方法里声明Site site参数取得当前站点, 返回值是模板名。带子目录的站点地址(/{子目录}/)由框架自动生成,路由里不要自己写子目录。article/… - 模板标签实现 FreeMarker 的
TemplateDirectiveModel,在ContextConfig里用configuration.登记名称。 每个取数据的标签都有一个参数相同的公开接口,见模板标签与 API 的通用参数。setSharedVariable("TagList", …)
四、后台接口的登录与权限
/api/backend/** 的请求依次经过:
令牌解析。请求头
Authorization: Bearer <令牌>由 Spring Security 解析成当前用户。这一层对/api/**整体放行,不判断权限。后台拦截器(
com.)。没有登录返回 401;处理方法和它所在的类都没有ujcms. cms. core. web. support. BackendInterceptor @PreAuthorize时返回 403;然后按请求头ujcms-site-id确定当前站点并检查用户能否进入该站点,把当前用户和当前站点放进Contexts。方法上的权限判断。每个处理方法声明自己需要的权限码:
java@GetMapping @PreAuthorize("hasAnyAuthority('tag:list','*')") public Page<Tag> page(...) { ... }
权限的规则:
- 权限码的形式是
资源:操作,如tag:list、tag:create。用户拥有的权限码是他所有角色的 功能权限 的合集。 - 角色开启了 全部功能权限 的用户拥有
*,所以每个注解都写成hasAnyAuthority('<权限码>',。'*') - 只要有后台角色就拥有
backend。不需要专门授权的只读辅助接口写hasAnyAuthority('backend',。'*') - 后台接口默认拒绝:漏写
@PreAuthorize的方法在运行时被拦截器以 403 拒绝,单元测试BackendControllerGuardTest也会在构建时报出来。 - 权限码要在后台界面的权限树里登记,角色才能被授予,见后台界面开发。
公开接口没有这一套:是否需要登录、能看到哪些数据,由各个 Controller 自己判断。
五、后台界面
ujcms-ui-console 使用 Vue 3.5、Vite 7、TypeScript、Element Plus、Pinia、Vue Router、Vue I18n 和 Tailwind CSS,包管理器是 pnpm, 需要 Node.js 22.12 或以上(安装见 Node.js 与 pnpm 安装)。src 下与二次开发有关的目录:
| 位置 | 内容 |
|---|---|
src/api/ | 调用后台接口的函数,按菜单分组分文件(content.ts、interaction.ts 等) |
src/views/ | 各个界面,按菜单分组分目录 |
src/ | 路由。左侧菜单就是按这个文件的顺序生成的 |
src/data.ts | 角色的权限树(getPermsTreeData())和操作日志的模块、名称列表 |
src/、src/locales/en/ | 界面文字,中英文各一套 |
src/components/ | 通用组件:对话框表单 DialogForm、查询表单 QueryForm、表格列设置 TableList 等 |
src/stores/、src/utils/ | 当前用户与权限判断(useCurrentUser.ts)、请求封装(request.ts)等 |
六、开发时的运行方式
- 在源码根目录执行
./mvnw clean spring-boot:启动后端(端口 8080)。run - 另开一个命令行窗口,执行
pnpm --dir ujcms-ui-console dev启动后台界面的开发服务器(首次先执行pnpm --dir ujcms-ui-console install),访问http:。开发服务器把/ / localhost: 5173 /api、/uploads、/themes的请求转发到http:(/ / localhost: 8080 ujcms-ui-console/里的. env VITE_PROXY_*),修改界面代码后浏览器即时刷新。 - 改完后执行
pnpm --dir ujcms-ui-console build:,把后台界面构建到starter ujcms-starter/, 再按源码根目录src/ main/ webapp/cp README.md里的命令打成 jar 或 war。 - 执行
./mvnw test运行后端的单元测试。测试会有意触发并断言各种异常,日志里出现异常堆栈是正常的,以末尾的BUILD SUCCESS为准。
七、接下来
增加一个自己的功能,从建表到出现在后台菜单里,按下面的顺序阅读:
- 数据库设计规范与表结构变更:表名、字段名和类型的约定,用变更日志建表、改表。
- 后端功能开发:实体类、Mapper、Service、Controller 各写什么。
- 后台界面开发:接口函数、列表与表单、路由与菜单、权限树。