1.3　建模工具与编码规范化

1.3.1　UML建模工具PlantUML

PlantUML是一个开源工具，允许用户使用纯文本语言创建UML图。PlantUML的语言是特定于域的语言的示例。它使用Graphviz软件来布置图表。PlantUML具有比较详细的各类语言的Guide文档。PlantUML实现了很多适配，对常用的编译器Eclipse、IDEA等都提供了对应的插件，同时PlantUML与Maven和jQuery都进行了集成，还提供了war包形式，可以在本地的Java EE容器（如Tomcat）中运行。

1.PlantUML的使用方式

PlantUML有如下几种使用方式。

（1）通过网站使用PlantUML绘制对应的UML图。PlantUML官网提供了免费的在线编辑服务，可以通过在输入区输入UML语言来生成对应的UML图，网址为http：// www.plantuml.com/plantuml/uml，如图1-24所示。

（2）通过本地的Java EE容器运行plantuml.war文件。下载Java J2EE WAR File（plantuml.war），并将其放在本地的Tomcat的webapps目录下，在启动后访问http：//localhost：8080/plantuml，就可以看到如图1-25所示的界面，可以在输入区编写PlantUML语言的代码。plantuml.war文件的下载地址为https：//sourceforge.net/projects/plantuml/files/plantuml.war/download。

（3）在IDEA中使用PlantUML Integration插件。在使用之前需要安装PlantUML Integration插件，然后就可以方便地书写UML语言，并生成对应的预览图片。我们可以复制或保存生成的图片到指定的目录，并重启IntelliJ IDEA。除了安装PlantUML Integration插件，还需要下载并安装Graphviz到Windows上，下载地址为https：//graphviz.gitlab.io/_pages/ Download/windows/graphviz-2.38.msi。

2.在IDEA中使用PlantUML进行建模

在IDEA中绘制UML图，可以通过选择【File】→【New】→【PlantUML File】命令来运行PlantUML，并且在弹出的对话框中选择要创建的UML图的类型，输入文件名，如图1-26所示。

这里主要介绍用例图和类图的建模方法。对于其他建模方法，可参见官方网站（http：// plantuml.com/zh/）的介绍。

1）用例图

用例图（Use-Case Diagram）是用于描述系统功能的视图，其主要元素是用例和参与者，可以帮助开发团队以一种可视化的方式理解系统的功能需求，并向客户形象化地表述项目的功能。使用PlantUML创建用例图的说明如表1-1所示。

2）类图

类图（Class Diagram）显示了模型的静态结构，特别是模型中存在的类、类的内部结构及它们与其他类的关系等。类图不显示暂时性的信息。类图是面向对象建模的主要组成部分。它既可以用于应用程序的系统分类的一般概念建模，也可以用于详细建模，将模型转换成编程代码，还可以用于数据建模。使用PlantUML创建类图的说明如表1-2所示。

1.3.2　数据库建模工具Workbench

Workbench是一款专门为MySQL设计的集成化桌面软件，也是下一代可视化数据库的设计和管理工具。该软件支持Windows和Linux系统，可以通过网址https：//dev.mysql.com/ downloads/workbench/下载。Workbench为数据库管理员和开发人员提供了一套可视化的数据库操作环境，主要功能有数据库设计与模型建立、SQL开发（取代MySQL Query Browser）、数据库管理（取代MySQL Administrator）。

Workbench包括开源社区版本和商业版本。

●Workbench Community Edition，也叫MySQL Workbench OSS，是在GPL证书下发布的开源社区版本。

●Workbench Standard Edition，也叫MySQL Workbench SE，是按年收费的商业版本。截至本书编写完成时，开源社区版本的最新版本为MySQL Workbench 8.0.19，其下载界面如图1-27所示。

在下载完成后可得到mysql-workbench-community-8.0.19-winx64.msi安装文件，双击该文件即可安装。在安装完成后，Workbench的运行起始界面如图1-28所示。

1.3.3　IDEA数据库管理工具

IDEA提供了数据库管理工具，我们可以利用这个工具建立数据库和数据表，操作数据，以及执行SQL语句。具体操作方法如下所述。

（1）在第一次使用时，可以选择【View】→【Tool Windows】→【Database】命令，打开数据库管理工具，如图1-29所示。然后会在右边栏出现【Database】按钮，以后就可以通过单击右边栏的【Database】按钮来快速打开数据库管理工具，如图1-30所示。

（2）单击数据库管理工具左上角的【+】按钮，然后选择【Data Source】→【MySQL】命令，建立MySQL数据源，如图1-31所示。

（3）在如图1-32所示的界面中进行连接配置，在【Name】文本框中输入一个名称，用来标识这个连接配置，并在下面的几个文本框中分别输入主机名、端口号、用户名和密码，以及数据库名称（如果数据库还未创建，则可以不输入数据库名称），然后单击【OK】按钮。

（4）在如图1-33所示的界面左侧输入区中输入创建数据库的SQL脚本。

（5）选择一段代码，然后单击按钮，在弹出的快捷菜单中选择第二个命令（执行所有SQL脚本），如图1-34所示。

（6）在SQL脚本执行成功后，即可创建数据库，已建立的数据库如图1-35所示。

1.3.4　基本编码规范与常用技术

编码规范对于软件本身和软件开发人员而言尤为重要。良好的编码规范可以改善软件的可读性，提高团队开发的合作效率，减少软件的维护成本，而且长期的规范性编码可以让开发人员养成良好的编码习惯，甚至锻炼出严谨的思维。

1.命名规范

（1）项目名称：项目名称一般采用缩写形式，所有字母均小写。

（2）包的分类名：包的分类名由小写字母构成，并使用圆点（.）来划分层次。一般格式如下：

第一部分是可选的，使用com表示公司，使用org表示组织。第二部分表示项目名称。第三部分表示包的分类名，例如，在按分层架构设计Web系统时，控制层、业务层接口、业务实现层、数据访问层接口、数据访问实现层、实体类（模型类）等一般使用controller、service、service.impl、dao、dao.impl、entity作为包的分类名。

（3）文件夹：在视图层划分文件夹可以方便文件的管理。文件夹采用小写英文单词表示。视图层一般按领域模型类来划分文件夹，例如，网上人才中心系统涉及用户、公司、职位、申请、个人等，因此可以建立user、company、job、application、person等文件夹，分别用来存放相关的视图文件，还可以建立images、css、js、common和upload等文件夹，分别用来存放界面图像、样式表、JavaScript脚本文件、公共网页和上传的文件等。

（4）文件名：类的文件名与类名相同，扩展名为java。网页的文件名可根据具体功能来命名，若使用JSP，则将添加（注册）页面文件、修改页面文件、浏览页面文件、管理页面文件、首页文件分别命名为add.jsp、edit.jsp、browse.jsp、manage.jsp、index.jsp等。

（5）类名与接口名：类名由一个或几个英文单词组成，采用大驼峰规则，即每个英文单词的第一个字母大写。类名一般使用完整的英文单词，避免使用缩写词（除非该缩写词被广泛使用，如Dao）。接口与类的命名类似。按分层结构设计系统，可采用以下命名规范。

●控制类：项目名+领域模型名+Controller。例如，RcUserController是网上人才中心系统中用户控制类的名称。

●模型类（实体类）：项目名+领域模型名。例如，RcUser是网上人才中心系统中用户模型类的名称。

●业务逻辑接口：项目名+领域模型名+Service。例如，RcUserService是网上人才中心系统中用户业务逻辑接口的名称。

●业务逻辑类：项目名+领域模型名+Service+Impl。例如，RcUserServiceImpl是网上人才中心系统中用户业务逻辑类的名称。

●数据访问接口：项目名+领域模型名+Dao。例如，RcUserDao是网上人才中心系统中用户数据访问接口的名称。

●数据访问类：项目名+领域模型名+Dao+Impl。例如，RcUserDaoImpl是网上人才中心系统中用户数据访问类的名称。

（6）方法名：方法名的第一个英文单词的首字母小写，其他英文单词的首字母大写，如getPersonInfo（）。此外，还有一些规范如下所述。

●属性方法遵循JavaBean命名规范：getXXX（）和setXXX（）。

●转换对象类型的方法一般被命名为toType（）形式，如toString（）。

●返回boolean类型的方法被命名为isXXX（）形式，如isTriangle（）。

●数据访问层的方法应尽量体现SQL操作。例如，将添加、修改、删除、按ID查询、根据条件查一个、根据条件查多个、查所有、按条件分页查询、查所有总数、按条件查总数的方法分别命名为insert、update、delete、selectById、selectOne、selectSome、selectAll、selectSomeByPage、selectAllCount、selectCount。

●业务逻辑层的方法应尽量反映业务功能，要求可读性强。例如，对于用户的业务逻辑层而言，将添加、修改、删除、按ID查询、查所有、按条件分页查询、查所有总数、按条件查总数的方法分别命名为addUser、editUser、deleteUser、findById、findAllUsers、findUsersByPage、findAllCount、findCount。

●控制类的方法反映了客户端请求，应将添加、登录、要修改、修改、删除、管理、浏览、查看等请求的方法分别命名为add、login、willEdit、edit、delete、manage、browse、show等。

（7）变量名与常量名：变量名一般采用小驼峰规则，即第一个英文单词的首字母小写，其后的英文单词的首字母大写。常量名由一个或多个被下画线分开的大写英文单词组成，如PAGE_SIZE。

2.注释规范

注释是在源程序中具有说明作用的语句，这种语句在编译时将被编译器忽略。注释是程序设计中不可或缺的组成部分，目的是增加程序的可读性。需要说明的是，因为本书的篇幅限制，书中所提供的代码省去或简化了注释。Java的注释包括以下3种。

●单行注释：以//开头，直到行的末尾。

●多行注释：以/*开头，直到*/结束，用来注释一行或多行。

●文档注释：以/**开头，直到*/结束，这是Java特有的注释方法，能被转化为HTML格式的帮助文档。

在Java EE程序设计中，注释一般遵循以下规范。

（1）源文件注释：源文件注释采用/*…*/，在每个源文件的头部，主要用于描述文件名、版权信息等。

（2）类注释：类注释采用/** … */，在类的前面，主要用于描述类的作用、版本、可运行的JDK版本、作者、时间等。可以使用的标记包括以下几种。

●@author：描述作者。

●@version：描述版本。

●@since：描述该类可以运行的JDK版本。

●@datetime描述该类建立的时间。

（3）方法注释：方法注释采用/**… */，在方法的前面，主要用于描述方法的功能、参数、返回值、异常等。可以使用的标记包括以下几种。

●@param：描述方法的参数。

●@return：描述方法的返回值。对于无返回值的方法或构造方法而言，@return可以被省略。

●@throws：描述在什么情况下抛出什么类型的异常。

（4）全局变量注释：如果是public类型的变量或常量，则应使用/**…*/注释对其进行重点说明。如果是其他类型的变量，则可以使用//注释进行简单说明，但是需要在它的设置（set方法）与获取（get方法）成员方法上加上方法注释。

（5）内部代码注释：方法内部的代码使用/*…*/或//进行注释，主要用于对代码进行一些必要的说明。

3.使用IDEA内置的功能生成注释

1）类注释模板

设置类注释模板的过程如下所述。

（1）选择【File】→【Setting】命令，打开配置对话框。

（2）选择【Editor】→【File and Code Templates】→【Class】选项，打开类注释的模板。

（3）在public class ${NAME} {的上一行插入自定义的模板，如图1-36所示。

上述7个变量说明如下所述。

●${NAME}：类的名称。

●${description}：在创建类时，提示输入类的描述。

●${YEAR}：完整的年份，如2020。

●${MONTH}：完整的月份，如02。

●${DAY}：完整的日期，如22。

●${HOUR}：24小时制的小时，如16。

●${MINUTE}：完整的分钟，如52。

在设置好后，创建新类时会弹出对话框，按提示输入描述的内容，就会自动生成注释。

2）方法注释模板

设置方法注释模板的过程如下所述。

（1）选择【File】→【Setting】命令，打开配置对话框。

（2）选择【Editor】→【Live Templates】选项，打开实时模板设置界面。

（3）单击界面右侧的绿色加号按钮，在弹出的下拉列表中选择【Template Group】选项，创建一个自定义的模板组，如图1-37所示。

（4）选择刚刚创建的模板组，单击界面右侧的绿色加号按钮，在弹出的下拉列表中选择【Live Template】选项，在该模板组下创建一个自定义的模板，如图1-38所示。

（5）选择刚刚创建的模板，在下方的【Abbreviation】文本框中输入【*】，并在【Template text】列表框中输入模板内容，如图1-39所示。

（6）单击【Edit variables】按钮，打开如图1-40所示的对话框，对模板变量进行设置，并在设置完成后单击【OK】按钮。

其中，description的【Expression】栏保持为空。

在params的【Expression】栏中输入：

在returns的【Expression】栏中选择【methodReturnType（）】选项。

（7）返回如图1-39所示的界面，单击界面下方【No applicable contexts】旁边的【Define】，在弹出的下拉列表中勾选【Java】复选框，选择可用的环境，如图1-41所示。然后单击其他地方关闭下拉列表，并单击【OK】按钮完成模板设置。

若要使用设置好的模板，则只需要在方法前输入【/*】并按回车键即可。

1.3.5　Spring Boot集成Swagger2

在团队开发中，一个好的API文档不但可以大大降低沟通成本，而且可以帮助新人快速上手业务。传统的做法是由开发人员创建一份RESTful API文档来记录所有的接口细节，并在程序员之间互相传递。这种做法存在以下几个问题。

（1）API接口众多，细节复杂，需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等。若想要高质量地完成这份文档，需要耗费大量的精力，并且难以维护。

（2）随着需求的变更和项目的优化、推进，接口的细节会不断地演变，因此接口描述文档也需要同步修订，但是文档和代码处于两个不同的媒介中，除非有严格的管理机制，否则很容易出现文档、接口不一致的情况。

Swagger2的出现就是为了从根本上解决上述问题。

1.Swagger2及其配置

Swagger是一组围绕OpenAPI规范构建的开源工具，可以帮助用户设计、构建、记录和使用RESTful API。作为一个规范和完整的框架，Swagger可以用于生成、描述、调用和可视化RESTful风格的Web服务。接口文档可以在线自动生成，并随接口变动实时更新，从而节省维护成本。同时接口文档支持在线接口测试，不依赖第三方工具。Swagger2是Swagger的当前版本，具有以下特点。

●代码变，文档变。只需要少量的标注，Swagger 就可以根据代码自动生成API文档，很好地保证了文档的时效性。

●跨语言性，支持40多种语言。

●Swagger UI呈现出来的是一份可交互式的API文档，我们可以直接在文档页面中尝试调用API，省去了准备复杂的调用参数的过程。

●可以将文档规范导入相关的工具（如Postman、SoapUI），这些工具将会创建自动化测试。

在项目中使用Swagger2，可进行以下配置。

1）引入依赖

2）创建配置类

上述类使用@Configuration标注，表明它是一个配置类；@EnableSwagger2表示开启Swagger2。

在通过createRestApi（）方法创建Docket的Bean之后，apiInfo（）方法用来创建该API的基本信息（这些基本信息会展现在文档页面中）；select（）方法用来返回一个ApiSelectorBuilder实例，控制哪些接口会暴露给Swagger；apis（）方法用来指定扫描的包以生成文档展现。本例指定了包路径，Swagger会扫描该包下所有Controller定义的API，并产生文档内容。

如果是Spring Boot与JSP结构的程序，还需要继承WebMvcConfigurer，并通过覆盖addResourceHandlers设置路径。

2.使用Swagger2

在项目中使用Swagger2主要通过以下标注。

●@Api：修饰整个类，描述Controller的作用。

●@ApiOperation：描述一个方法。

●@ApiImplicitParam：描述一个参数，可以配置参数的中文含义，也可以给参数设置默认值，从而在接口测试时可以避免手动输入。

●@ApiImplicitParams：如果有多个参数，则需要使用多个@ApiImplicitParam标注来描述，多个@ApiImplicitParam标注需要放在一个@ApiImplicitParams标注中。

●@ApiModel：描述模型类。

●@ApiModelProperty：描述模型类的属性。

●@ApiIgnore：用于方法或类，表示这个方法或类被忽略。

●@ApiError：描述发生错误时返回的信息。

●@ApiResponse：HTTP响应其中一个描述。

●@ApiResponses：HTTP响应整体描述。

1）类描述

@Api用于描述类，说明该类的作用。可以标记一个Controller类作为Swagger文档资源，使用方式如下：

2）方法描述

@ApiOperation用于描述一个方法，基本格式如下：

例如：

3）方法各参数描述

单个参数用@ApiParam描述，基本格式如下：

例如：

多个参数用@ApiImplicitParams描述，并通过@ApiImplicitParam对每个参数进行描述，基本格式如下：

@ApiImplicitParam的基本格式如下：

例如：

响应结果用@ApiResponse描述，基本格式如下：

多个响应用@ApiResponses描述。例如：