开发手册

ZrLog 开发手册

阅读本手册内容，需要一定的学习能力

版本说明

版本	发布时间	说明	作者
v1.0	2015-9-30	文档初始化	@94fzb
v1.1	2016-3-22	加入插件拦截的请求路径	@94fzb
v1.2	2018-3-27	——	@94fzb
v1.3	2021-10-17	调整技术方案	@94fzb
v1.4	2024-02-02	1. 无需Servlet容器 2. JDK 版本须 >=21	@94fzb

使用的基本技术

JDK21
Maven
MySQL
AntD
React

对，没了，这里你不会看到，仅因为做一个简单的检索，就要搞个 elasticsearch 有或者是 lucene/solr ，为了做个数据缓存就要去安装一个 redis，为了写文章能发到微信公众号，你可能还需要去学习下微信公众号的开发使用，或者接入一些奇奇怪怪的第三方服务

开发工具

由于 ZrLog 使用的未使用标准的 Servlet 容器，所以即使你使用记事本也可以进行开发的（开心就好），甚至你还可以用 vscode ，当然这里推荐使用 idea，如果觉得没钱买专业版本，有觉得用盗版过意不去，那么选择 idea 社区版本也是完全可以的

开发环境搭建

idea 导入项目会提示Add as a maven project
eclipse 自己导入的时候选择 maven 方式导入

提供了两种方式启动程序

直接找到 com.zrlog.web.Application 通过这个 main() 进行启动
通过 Maven 命令的方式进行启动（不依赖任何 IDE）
- Windows 使用 bin\mvn-run.cmd
- Unix 使用 sh bin/mvn-run.sh

通常有调试需求用第一种方式，平时进行开发使用第二种（这里要论一块 SSD 的重要性了）

数据初始化

很多网友还会认为程序没有使用数据库，这简直是个天大的误会呀，之所以你能启动 main 就可以看到一个正常运行的程序，那完全是应为有意而为之的（方便有开发能力的朋友一眼就清楚理解是不是自己想要的东西呀）

所以你要自己的数据库，需要做的是自己安装 MySQL ，然后为程序创建一个数据库，再然后删除项目里面的 install.lock 文件，然后访问程序，程序内置的安装向导回引导你完成数据库初始化的，然后你可以定制自己的需求

模块间的依靠关系

为了防止编写代码的时候出现在 common 里面调用 dao 的方法，所以基本依赖关系就是，web->service->data->common 这样的单向依赖

路由的约定

由于只是单用户博客系统，设计之初就没有太多的权限控制

ZrLog 只有2种用户模式（需要登录的，和访客模式）

游客
- /install/ (通过install.lock 文件控制访问) （React）
- / (与博客相关的)
- /p/ /plugin/ (与插件相关的，第三方接口的 callback 畅言使用)
- /api/ (开放与博客相关的所有JSON数据)
- /xxx (可以自行进行扩展)
管理员
- /admin/ （React）
- /admin/plugins/ 插件核心页面使用 React，单个插件可自选页面技术
- /api/admin

主题

目前得写 ftl 模版了，都是简单的几行代码就行了，会 <c:if></c:if>,${log.content} 这种基础语法就够了

主题开发

插件

相当详细的介绍

升级逻辑

为了方便广大的程序使用者都能轻松使用到最新的 ZrLog，所以提供了在线升级的功能，理论支持所有操作系统，升级仅支持非 Docker 模式下，通过 JarUpdater 实现（当然也要注意万恶的 window 文件锁问题，如果升级失败可自己手动停止程序，解压最新的 zip 包，后再启动）

website表

理论上这张表是存放程序相关设置的表的，理解为一个巨型的字典（Map）就可以了，如果你需要扩展设置，推荐直接使用这张表，比如现在于插件相关的信息都是存放在这张表里面的

部署

ZrLog 使用 zip 进行发布，所以仅需要使用 maven 打包 zip（mvn clean install），并上传到对应的服务器上面就可以了，甚至你可以自己利用 Jenkins 进行持续集成都是没有问题的，唯一要注意的是如果想发布过程中不出现中断，注意好代码里面的资源释放就可以，如果你还做了区分环境也仅需要将对应环境的 db.properties 的压缩打 zip 里面

当然，除了上面一种方式，成为程序的开发者，就是把改动的代码合并到 zrlog/master 的主干分支上面

设计原则

ZrLog 从一开始就把程序定位简洁，小巧，实用，旨在输出内容，而不是在程序的使用上

JSON API

JSON API 主要用于非网页展示，用于客户端程序开发定制

注意事项

默认所有的 ftl 页面都不能通过浏览器访问

开源协议

若非特别说明，所有源码按 Apache 标准使用即可