zrlog 开发手册

记录 / 2018-03-26

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

使用的基本技术

JDK1.8
Maven
MySQL
JFinal
AntD
React

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

开发工具

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

开发环境搭建

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

提供了三种方式启动程序

直接通过内嵌入 tomcat 的方式进行启动，找到 com.zrlog.web.Application 通过这个 main() 进行启动
通过 Maven 命令的方式进行启动（不依赖任何 IDE）
- Windows 使用 bin\mvn-tomcat-run.cmd
- Unix 使用 sh bin/mvn-tomcat-run.sh
配置 server 的方式与其它web程序一致（不建议使用，上面的方式出问题的可能性更小）

通常有调试需求用第一种方式，平时进行开发使用第二种（这里要论一块 SSD 的重要性了），当你知道 tomcat 还可以内嵌后，估计你就再也不想自己手动配置 server

数据初始化

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

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

模块间的依靠关系

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

路由的约定

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

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

游客
- /install/ (通过install.lock 文件控制访问) （React）
- / (与博客相关的)
- /p/ /plugin/ (与插件相关的,第三方接口的 callback 多说使用)
- /api/ (开放与博客相关的所有JSON数据)
- /xxx (可以自行进行扩展)
管理员
- /admin/ （React）
- /api/admin

主题

目前还是得写 JSTL，当然你也可以选择使用 JFinal 提供 enjoy 模板，又或是 freemarker，都是简单的几行代码就可以支持的

主题开发

插件

相当详细的介绍

升级逻辑

为了方便广大的程序使用者都能轻松使用到最新的 ZrLog，所以提供了在线升级的功能，理论支持所以按 J2EE 标准实现的容器

原理

利用容器会自动检查 war 是否更新，通常容器默认都会打开这项特性（已知 WebLogic 除外），所以实现上面只需要下载新的 war 包，然后使用 Java 提供 JarOutputStream 合成新的 war 进行覆盖就可以了，当然带来的问题是更新过程中，需要手动释放一些资源，避免出现内存泄漏，当然也要注意万恶的 window 文件锁问题

website表

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

部署

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

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

设计原则

ZrLog 从一开始就把程序定位简洁，小巧，实用

JSON API

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

注意事项

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

开源协议

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