# 介绍

本系列文档着重讲解如何进行开发和部署。

# 开发环境

在着手开发之前,请您提前安装/学习如下环境

  • Java8,Torna要求Java版本最低为Java8
  • Maven3,包管理以及构建工具,最低版本要求maven3
  • nodejs12,前端开发需要安装nodejs,建议版本12,版本太高可能会有问题
  • Mysql5.7(推荐)

工程说明

  • front: 前端工程
  • plugin: 插件
  • script: 辅助脚本
  • sdk: OpenAPI对应的SDK
  • server: 服务端工程
  • mysql.sql:数据库脚本

# 导入项目

本项目采用IDEA进行开发,Eclipse理论上也能支持。

由于Torna基于SpringBoot,因此完全可以使用社区版本的IDEA进行开发。

具体导入步骤如下:

  • 导入MySQL脚本,MySQL5.6.5及以后的版本执行mysql.sql,5.6.5之前的版本见:支持低版本MySQL
  • IDE安装lombok插件,然后打开项目(IDEA下可以打开根pom.xml,然后open as project),初次导入会下载依赖包,请耐心等待
  • 打开server/boot/src/main/resources/application.properties,修改数据库配置
  • 运行server/boot/src/main/java/cn/torna/TornaApplication.java

至此,服务端启动完毕,下面讲解运行前端工程

运行前端

cd front,将命令提示符跳转到front目录

  • 执行npm install

这一步是下载nodejs相关依赖

  • 执行npm run dev,访问http://localhost:9530/

至此前端启动完毕

前端请求的服务器地址配置在.env.development文件中,默认是http://localhost:7700

IDE打开前端项目

使用WebStormVSCode打开front文件夹,如果您是后端Java开发人员,推荐使用WebStorm,界面熟悉一点,全家桶快捷键也一样。

# 项目架构

服务端

基于SpringBoot-2.3.4,模块说明

  • boot:负责启动&文件配置
  • server-api:OpenAPI相关接口,基于 easyopen (opens new window) 实现
  • server-common:公共的类,util等文件
  • server-dao:数据库操作层,存放Mapper和实体类,基于 fastmybatis (opens new window)
  • server-manager:第三方服务类
  • server-service:业务层,处理具体业务
  • server-web:控制层,存放Controller

下面对server-web模块做进一步说明

cn.torna
└── web
    ├── config          # 存放Configuration
    ├── controller      # 存放controller
    │    ├── admin      # 超级管理员相关功能
    │    ├── doc        # 文档功能
    │    ├── module     # 模块功能
    │    ├── openuser   # 开放用户功能
    │    ├── project    # 项目功能
    │    ├── space      # 空间功能
    │    ├── system     # 系统功能
    │    └── user       # 登录用户功能
    └── interceptor     # 拦截器

前端

基于 vue-admin-template (opens new window) ,控件库使用 ElementUI (opens new window)

如果您对前端开发不太熟,但想学习,可以先系统学习如下内容:

Torna前端项目在front目录下,文件结构如下:

front
├── build       # 无需关注
├── mock        # 无需关注
├── public      # 存放公共文件,即网站根目录
├── src
│    ├── api        # 无需关注
│    ├── assets     # 静态资源
│    ├── components # Vue公共组件
│    ├── icons      # icon图标
│    ├── layout     # 主布局
│    ├── layout_admin # 超级管理员对应的布局
│    ├── layout_view # 浏览模式对应的布局
│    ├── router     # 路由相关
│    ├── store      # 存储相关
│    ├── styles     # 样式
│    ├── utils      # 存放js工具类
│    └── views      # 功能视图
│           ├── admin       # 超级管理员对应的功能
│           ├── common      # 公共视图,登录、注册、404等
│           ├── dashboard   # 首页
│           ├── doc         # 文档功能
│           ├── help        # 帮助中心
│           ├── project     # 项目功能
│           ├── redirect    # 跳转辅助
│           ├── space       # 空间功能
│           ├── user        # 用户中心
│           └── view        # 浏览模式
└── tests

# Hash ID

为了避免把主键id值暴露给前端页面,系统会把id做一次hash,然后返回给前端,因此在json序列化时,需要把id转成hashId,反序列化时需要把hashId转成id

在所有的返回、接收参数中,任何涉及到主键字段的都需要加上@JSONField(serializeUsing = IdCodec.class, deserializeUsing = IdCodec.class)

public class DocInfoVO {
    @JSONField(serializeUsing = IdCodec.class, deserializeUsing = IdCodec.class)
    private Long id;
}

如果只有单个参数,需要加上@HashId注解,如下所示

    @GetMapping("list")
    public Result<List<DocInfoVO>> listProjectDoc(@HashId Long moduleId) {
        List<DocInfo> docInfos = docInfoService.listDocMenu(moduleId);
        List<DocInfoVO> docInfoVOS = CopyUtil.copyList(docInfos, DocInfoVO::new);
        return Result.ok(docInfoVOS);
    }

手动计算hashId可以使用IdUtil.encode(val)IdUtil.decode(hash),示例代码如下:

    @Test
    public void testGen() {
        Long val = 711111231231235L;
        String hash = IdUtil.encode(val);
        System.out.println(hash);

        Long val2 = IdUtil.decode(hash);
        Assert.assertEquals(val, val2);
    }

# 调试服务端

默认情况下调试程序需要同时启动前端页面和后端服务,但有时候只想调试服务端程序,不想启动前端。

这种情况下可以先把编译好的前端资源放到本地目录,然后启动服务的时候手动指定静态资源路径即可。

  • 第一步:前往 发行版页面 (opens new window) 下载最新版本zip
  • 解压zip,复制dist文件夹路径,如:D:\downloads\torna-1.11.1\torna-1.11.1\dist
  • IDEA启动项新增启动参数指定dist所在目录:--torna.front-location=D:\downloads\torna-1.11.1\torna-1.11.1\dist,或者VM参数:-Dtorna.front-location=D:\downloads\torna-1.11.1\torna-1.11.1\dist,两者二选一

启动服务,访问http://localhost:7700即可

# 打包部署

开发完成后,需要对项目进行打包发布,步骤如下:

如果您的开发环境为macOS/Linux系统,执行sh build.sh,如果是Windows系统双击执行build.bat

构建结果在dist/torna-<version>目录,最终结构如下:

torna-<version>                 # 根目录
├── application.properties      # 配置文件
├── dist                        # 前端资源
├── debug.sh                    # 线上调试
├── shutdown.sh                 # 结束服务脚本
├── startup.bat                 # 启动服务脚本(windows)
├── startup.sh                  # 启动服务脚本(macOS/Linux)
└── torna.jar                   # 服务程序

torna-<version>文件夹上传到服务器

修改application.properties配置文件内容,改为线上配置

执行startup.sh,启动应用(Windows执行startup.bat

访问:http://ip:7700

# nginx配置contextPath

如果需要在Nginx中配置一个contextPath,如/torna,步骤如下:

  1. 设置Nginx的contextPath
 location /torna {
    ...
 }
  1. application.properties中指定同样的contextPath

server.servlet.context-path=/torna

重启即可

# 使用MariaDB

与使用Mysql没有什么区别,可以直接切换到MariaDB,需要注意的是MariaDB版本。

MariaDB版本是5.5及以下,需要导入mysql_compat.sql内容,如果高于5.5版本如:10.x,则导入mysql.sql内容