如何优雅的跑起一个Demo

前言

本周我开始接触英文Spring教程的翻译，为了让读者理解的更透彻，我们翻译网站中的每一篇教程，都在GitHub上有一个完整的Demo供读者浏览。

那么，如何优雅的跑起一个Demo呢？

准备阶段

首先要想的是，这个Demo用来演示什么功能？需要哪些依赖？文件如何分层？

功能

例如，我需要翻译的这篇文章来自baeldung，原文《 [Spring Data JPA Query
](https://www.baeldung.com/spri... 》

这篇教程讲的是JPA的查询，因此在Spring项目结构中，只需要 Repository仓库层 和 Entity实体 即可。

数据库

然后是数据库的选用，一开始打算使用MySQL，配置地址、端口...等等，后来发现没必要——因为Demo是不需要把项目跑起来的，我们只需要写好功能代码，然后为每段代码创建单元测试，最终测试结果和预期一致，就实现了展示教程中的功能的效果。

这种需求，一个H2数据库解决所有问题，而配置文件完全不需要。
当没有数据库配置文件时，所有的单元测试都会自动在H2内存数据库中执行。

依赖

Spring Initializr为我们提供了快速初始化Spring项目的能力。

但是直到笔者写完这篇文章，这个网站一直都打不开，可能是官方的服务器出现了问题，下面用截图代替。

最新版本的Spring Initializr分为左右两部分，左侧是基本设置，右侧是为项目添加依赖。关于如何初始化项目的内容，请移步教程。

在网站的右侧，点击Add Dependencies就可以添加依赖了。

刚才提到，在笔者这个Demo中，只需要单元测试，不需要启动，因此只要有H2数据库就够了，如果需要在运行时查看数据库内容，也可以加上Spring Web。
如果是更复杂的Demo，可能还需要用到Mysql进行实际的启动。

依赖添加完毕后，一个初始化的Spring项目就创建完成，点击Generate就可以下载ZIP包了：

初始化仓库

在GitHub上创建空仓库，创建后如下：

在本地创建一个存项目的文件夹：

cd ~
mkdir test

把仓库clone到本地的文件夹中：

git clone <仓库地址> test

clone成功后，就可以把刚才下载的ZIP包，解压到项目文件夹了。

解压完毕后，git马上就能检测到代码改动。这是就可以把初始化的项目push上去，以便代码写错时及时恢复：

cd test
git add .
git commit -m Init
git push origin master

传输完毕后就可以正式开始启动项目了。

编写阶段

用IDEA打开pom.xml，装好依赖，就可以开始编写Demo。

Entity实体层

现有实体，才有仓库，因此第一步先来创建实体。

在笔者的Demo中只需要一个User对象，建立即可。
写上属性和setter、getter方法。
注意主键ID需要自增。

@Entity
public class User {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    // id 自增
    private Long id;
    // 姓名
    private String name;
    // 状态
    private Integer status;
    // 邮箱
    private String email;

    public Long getId() {
        return id;
    }

    public void setId(Long id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public Integer getStatus() {
        return status;
    }

    public void setStatus(Integer status) {
        this.status = status;
    }

    public String getEmail() { return email; }

    public void setEmail(String email) { this.email = email; }
}

初始化数据

为了进行单元测试，需要初始化一些测试数据。
我们使用的是H2数据库，H2是不需要配置文件的，当没有配置文件时，自动启动H2完成测试。

所以需要一个SQL文件，每次启动前自动执行一次即可。

在resources中新建data.sql，创建初始数据：

drop table if exists user CASCADE;
create table user (id bigint not null AUTO_INCREMENT, name varchar(255), status int(11), email varchar(255), primary key (id));
insert into user values (1, 'zhangsan', 1, '[e-mail]');
insert into user values (2, 'lisi', 0, '[e-mail]');
insert into user values (3, 'wangwu', 1, '[e-mail]');
insert into user values (4, 'zhaoliu', 0, '[e-mail]');
insert into user values (5, 'sunqi', 0, '[e-mail]');

确保数据表的结构和实体一致，如果不一致将导致项目启动失败。

Repository仓库层

文章讲解的主要内容就是仓库层，创建好接口之后，就可以开始翻译文章了。

然后为每个方法编写一个单元测试：

在类名上 Option + Enter，选择Create Test，就可以快速创建测试类。

注释

作为一个对读者负责的Demo，代码中的注释应该尽可能帮助读者去理解。这里给出两张截图供参考：

Readme.md

笔者认为，一个项目是否有Readme，是这个项目是否规范的一个证明。

在Readme中应向读者介绍项目的基本情况、引用了什么依赖、需要配置哪些环境、以及帮助读者把项目跑起来等等。

总结 一切为读者

在我看来，一个好Demo的关键，不在于代码多么高级，而是如何让读者更容易理解。
所以教程也好、Demo也好，都是为读者服务。
注释和说明文档，为我们的合理表达，提供了很好的工具。

版权声明

本文作者：河北工业大学梦云智开发团队 - 刘宇轩
新人经验不足，有建议欢迎交流，有错误欢迎轻喷