企业官网建设流程全解析

1. 为什么我放弃了 Swagger 转向 JApiDocs

接口文档这件事，做过 SpringBoot 项目的人都有体会。写代码两小时，补文档一整天，改完接口还得回头同步文档，稍微一偷懒，文档就和实际接口对不上了。团队里前后端联调的时候，前端拿着过期的文档来问“这个字段怎么没了”，后端一脸茫然“我上周就改了啊”，这种场景几乎每个项目都上演过。

我最早用的是 Swagger 那一套，后来也试过各种增强方案。Swagger 的问题不在于功能，而在于它要求你在代码里塞一堆注解——@Api、@ApiOperation、@ApiModelProperty，每个 Controller、每个方法、每个字段都得标注。项目小的时候还能忍，项目一大，代码里全是注解噪音，业务逻辑被淹没在文档注解里。更麻烦的是，注解和代码是两套东西，改了代码忘了改注解，文档照样失真。

后来接触到 JApiDocs，第一反应是“这玩意儿真能不加注解就生成文档？”用下来发现确实可以。它的核心思路和 Swagger 完全不同：Swagger 是“你告诉我文档长什么样”，JApiDocs 是“我自己读你的代码，推断出文档应该长什么样”。它通过解析 Java 源码的 AST（抽象语法树），结合 SpringBoot 的注解（@RequestMapping、@GetMapping、@PostMapping这些本来就要写的），自动提取接口信息、参数结构、返回值类型，然后生成 HTML 文档。

这意味着什么？意味着你写业务代码的时候完全不用管文档，代码写完，跑一下 JApiDocs，文档就出来了。接口改了，重新生成一次，文档自动同步。对于我这种懒人来说，这简直是解放。

但“无需额外注解”这个卖点背后，也藏着不少坑。JApiDocs 的推断能力有边界，遇到复杂场景它会猜错，或者干脆猜不出来。这篇文章就是把我踩过的坑一个个摊开讲，包括它到底怎么工作的、哪些场景会翻车、怎么配置才能让它听话、以及那些官方文档里没写的实操细节。

如果你正在用 SpringBoot 写后端，被接口文档折磨过，或者正在选型文档工具，这篇内容应该能帮你省下不少试错时间。我会从原理讲到实操，从配置讲到避坑，尽量把每个“为什么”都说清楚。

2. JApiDocs 的解析机制与能力边界

2.1 它到底是怎么“读懂”你的代码的

JApiDocs 的工作流程可以拆成三步：源码解析、信息推断、文档渲染。

第一步，它用 JavaParser 这个库把.java源文件解析成 AST。AST 是什么？你可以把它理解成代码的“骨架图”——编译器眼里，你的代码不是文本，而是一棵树，类是什么、方法是什么、参数是什么、返回什么，全都结构化地挂在树上。JApiDocs 遍历这棵树，找到所有带 SpringBoot 映射注解的方法，这些就是它要生成文档的接口。

第二步，信息推断。这是 JApiDocs 最核心也最容易出问题的地方。它需要推断出：这个接口的 URL 是什么、请求方法是什么、需要哪些参数、参数是什么类型、返回什么结构。URL 和请求方法直接从@RequestMapping系列注解里读，这个不会错。但参数和返回值就没那么简单了——它得看方法的形参列表、看返回类型、看字段上的注释（Javadoc），然后拼出一个完整的结构。

第三步，渲染。JApiDocs 内置了一套 HTML 模板，把推断出来的信息填进去，生成静态页面。你也可以自定义模板，但大多数人用默认的就够了。

关键点在于：JApiDocs 的推断完全基于源码，它不运行你的程序，不反射，不启动 Spring 容器。这意味着它速度快、不依赖运行环境，但也意味着它看不到运行时的动态信息。比如你用了 AOP 在运行时修改了返回值结构，JApiDocs 是不知道的。

2.2 哪些注解它认，哪些它不认

JApiDocs 对 SpringBoot 注解的支持是有选择的。它认这些：

• @Controller/@RestController：识别这是不是一个接口类
• @RequestMapping/@GetMapping/@PostMapping/@PutMapping/@DeleteMapping/@PatchMapping：识别 URL 和请求方法
• @RequestParam/@PathVariable/@RequestBody：识别参数来源
• @RequestHeader：识别请求头参数

它不认或者支持有限的：

• @ApiIgnore这类 Swagger 注解：JApiDocs 有自己的忽略机制，不依赖 Swagger
• 自定义的组合注解：如果你自己封装了一个@MyGetMapping，JApiDocs 默认不认识，需要额外配置
• @ModelAttribute：支持不完整，复杂场景容易出问题
• 泛型嵌套：多层泛型嵌套时，类型推断可能失败

这里有个很重要的认知：JApiDocs 不是万能的，它的设计目标是覆盖 80% 的常见场景，剩下 20% 的复杂场景需要你手动干预。理解这一点，后面的坑就好理解了。

2.3 和 Swagger 的本质差异决定了坑的位置

Swagger 是“声明式”的，你告诉它什么，它就展示什么。JApiDocs 是“推断式”的，它从代码里猜，猜对了皆大欢喜，猜错了你得想办法告诉它正确答案。

这个差异导致了一个有趣的现象：Swagger 的坑主要在“写注解太累”和“注解与代码不同步”，而 JApiDocs 的坑主要在“它猜错了怎么办”和“它猜不出来怎么办”。

举个例子。Swagger 里你写@ApiModelProperty(value = "用户ID", required = true)，文档就显示“用户ID，必填”。JApiDocs 里你没有这个注解，它只能从字段名userId和 Javadoc 注释里推断。如果你没写 Javadoc，它就只能显示字段名userId，没有中文说明。这时候你就得补 Javadoc，或者用 JApiDocs 提供的@ApiDoc注解来补充说明。

所以 JApiDocs 的“无需额外注解”是有前提的：你的代码本身要有足够的“可读性”——字段命名规范、Javadoc 完整、类型清晰。如果代码写得随意，JApiDocs 生成的文档也会很随意。

3. 环境搭建与基础配置中的隐藏细节

3.1 依赖引入的版本选择

JApiDocs 的依赖引入很简单，Maven 里加这么一段：

<dependency> <groupId>io.github.yedaxia</groupId> <artifactId>japidocs</artifactId> <version>1.4.4</version> </dependency>

版本选择上有个坑：不同版本对 Java 版本和 SpringBoot 版本的支持不一样。1.4.x 系列对 Java 8 支持最好，如果你用的是 Java 11 或 17，建议用最新的 1.4.4 或更高版本。我试过在 Java 17 项目里用 1.4.2，解析某些语法时直接报错，升级到 1.4.4 就好了。

另外，JApiDocs 是编译期工具，不是运行时依赖。理论上你可以把它设为provided或者只在开发环境引入，避免打包进生产 jar。但实操中我发现，如果你在 CI/CD 流程里自动生成文档，那它需要在构建阶段可用，所以还是放在默认 scope 里比较省事。

3.2 生成文档的三种触发方式

JApiDocs 生成文档有三种方式，各有适用场景。

第一种，写一个 main 方法手动跑：

public class DocGenerator { public static void main(String[] args) { DocsConfig config = new DocsConfig(); config.setProjectPath("/path/to/your/project"); config.setProjectName("MyProject"); config.setApiVersion("V1.0"); config.setDocsPath("/path/to/output"); config.setAutoGenerate(Boolean.TRUE); Docs.buildHtmlDocs(config); } }

这种方式适合本地开发时手动生成，改完代码跑一下，看看文档效果。

第二种，用 Maven 插件在构建时自动生成。JApiDocs 没有官方 Maven 插件，但你可以用exec-maven-plugin来调 main 方法：

<plugin> <groupId>org.codehaus.mojo</groupId> <artifactId>exec-maven-plugin</artifactId> <version>3.1.0</version> <executions> <execution> <phase>compile</phase> <goals> <goal>java</goal> </goals> <configuration> <mainClass>com.example.DocGenerator</mainClass> </configuration> </execution> </executions> </plugin>

这样每次mvn compile的时候文档就自动更新了。但要注意，这会增加构建时间，项目大的话可能多花十几秒。

第三种，用单元测试触发。写一个@Test方法，在里面调Docs.buildHtmlDocs(config)。这种方式的好处是可以在 IDE 里一键运行，而且不会影响正常构建。

我个人的习惯是：本地开发用 main 方法，CI 流水线里用 Maven 插件，确保每次提交代码后文档都是最新的。

3.3 项目路径配置的坑

setProjectPath这个配置看起来简单，但坑不少。它要的是项目源码的根目录，不是编译后的 class 目录。如果你填错了，JApiDocs 会找不到源文件，生成的文档就是空的。

在 IDE 里跑的时候，相对路径是相对于工作目录的。比如你在 IDEA 里跑 main 方法，工作目录默认是项目根目录，那setProjectPath(".")可能就能用。但如果你在子模块里跑，相对路径就变了。最稳妥的做法是用绝对路径，或者用System.getProperty("user.dir")动态获取。

还有一个坑：如果你的项目是多模块的，setProjectPath只能指定一个路径。JApiDocs 不会自动扫描子模块。解决办法是分别对每个模块生成文档，或者把projectPath设成父目录，然后看它能不能递归扫描——实测下来，JApiDocs 对多模块的支持有限，它只会扫描指定目录下的源码，不会深入子模块的src目录。所以多模块项目建议每个模块单独配置。

3.4 输出目录与静态资源处理

setDocsPath指定输出目录。JApiDocs 会在这个目录下生成 HTML 文件、CSS、JS 等静态资源。如果你把这个目录设在src/main/resources/static下，那启动 SpringBoot 后可以直接通过浏览器访问文档。

但这里有个坑：JApiDocs 每次生成会覆盖整个输出目录。如果你在输出目录里放了自定义的 CSS 或图片，会被清掉。解决办法是把自定义资源放在另一个目录，生成后再手动拷贝，或者用 JApiDocs 的自定义模板功能。

另外，生成的 HTML 默认用的是相对路径引用静态资源。如果你把文档部署到子路径下（比如http://example.com/docs/），需要确保资源路径正确。JApiDocs 默认生成的路径是相对当前 HTML 文件的，所以只要整个目录一起部署，一般没问题。

4. 参数解析翻车现场与修复方案

4.1 简单参数：为什么你的参数名变成了 arg0

这是 JApiDocs 最常见的坑之一。你写了一个接口：

@GetMapping("/user") public User getUser(String userId, Integer age) { // ... }

生成文档后，参数名显示的是arg0和arg1，而不是userId和age。

原因在于：Java 编译成 class 文件后，方法参数名默认是不保留的，会变成arg0、arg1。JApiDocs 解析的是源码，理论上应该能拿到参数名，但如果你用的 Java 版本或者编译配置有问题，它可能拿不到。

解决办法有两个。第一个是在编译时加上-parameters参数，让编译器保留参数名。Maven 里配置：

<plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-compiler-plugin</artifactId> <configuration> <compilerArgs> <arg>-parameters</arg> </compilerArgs> </configuration> </plugin>

第二个是在参数上加@RequestParam注解并指定名称：

@GetMapping("/user") public User getUser(@RequestParam("userId") String userId, @RequestParam("age") Integer age) { // ... }

这样 JApiDocs 就能从注解里读到参数名。虽然多写了几个字，但最稳妥。

4.2 对象参数：字段注释丢失的根因

当你用对象接收参数时：

@PostMapping("/user") public User createUser(@RequestBody UserDTO userDTO) { // ... }

JApiDocs 会去解析UserDTO这个类的字段。如果字段上没有 Javadoc 注释，文档里就只有字段名，没有中文说明。

public class UserDTO { private String userName; // 文档里只显示 userName private Integer age; // 文档里只显示 age }

要让它显示中文说明，你得加 Javadoc：

public class UserDTO { /** 用户名 */ private String userName; /** 年龄 */ private Integer age; }

这里有个细节：JApiDocs 读的是字段上方的 Javadoc，不是行尾注释。你写private String userName; // 用户名它是读不到的，必须用/** */格式。

还有一个坑：如果字段是private的，JApiDocs 默认也能读到，因为它解析的是源码不是反射。但如果你用了 Lombok 的@Data自动生成 getter/setter，JApiDocs 不会去读 getter 上的注释，它只读字段本身的注释。所以注释要写在字段上，不是 getter 上。

4.3 嵌套对象与泛型：推断失败的高发区

嵌套对象是 JApiDocs 最容易翻车的地方。比如：

public class OrderDTO { private String orderId; private UserDTO user; private List<ProductDTO> products; }

JApiDocs 能推断出user是UserDTO类型，products是List<ProductDTO>，然后递归解析UserDTO和ProductDTO的字段。但如果嵌套层级太深，或者泛型嵌套太复杂，它可能就放弃了。

我遇到过最典型的情况是Map<String, List<Object>>这种结构，JApiDocs 直接显示成Map，里面的结构完全丢失。这种场景没有太好的自动解决办法，只能手动加注释说明，或者在文档生成后手动补充。

另一个坑是泛型继承。比如你有一个基类BaseResponse<T>，然后UserResponse extends BaseResponse<UserDTO>。JApiDocs 解析UserResponse时，可能无法正确推断出T是UserDTO，导致返回结构显示不完整。解决办法是在UserResponse里显式声明字段，或者用 JApiDocs 的@ApiDoc注解手动指定。

4.4 日期、枚举等特殊类型的处理

日期类型Date和LocalDateTime，JApiDocs 默认会显示成对象结构（因为它们是类），而不是显示成字符串。这会让文档看起来很乱。解决办法是在配置里指定日期格式，或者用 JApiDocs 的@ApiDoc注解标注。

枚举类型Enum，JApiDocs 会显示枚举类名，但不会列出所有枚举值。如果你想让文档显示枚举的可选值，需要在枚举字段上加注释说明，或者用自定义模板处理。

还有一个容易被忽略的：Boolean和boolean的区别。JApiDocs 对基本类型和包装类型的处理略有不同，基本类型不会显示“可为空”，包装类型会。这个细节在文档里很重要，前端需要知道哪些字段可能为 null。

5. 让 JApiDocs 按你的意图工作的进阶配置

5.1 自定义注解与组合注解的支持

SpringBoot 项目里经常会有自定义的组合注解，比如：

@Target(ElementType.METHOD) @Retention(RetentionPolicy.RUNTIME) @RequestMapping(method = RequestMethod.GET) public @interface MyGetMapping { String value() default ""; }

JApiDocs 默认不认识@MyGetMapping，会把它当成普通方法，不生成接口文档。解决办法是在配置里注册自定义注解：

config.addPlugin(new CustomAnnotationPlugin());

或者更简单的方式：在DocsConfig里设置setAutoGenerate(true)，然后确保你的自定义注解上标注了@RequestMapping。JApiDocs 会递归查找注解上的元注解，如果发现@RequestMapping，就能识别。

实测下来，这个递归查找的深度有限，如果注解嵌套层级太多，还是可能失败。最稳妥的做法是避免过度封装，或者在文档生成时用@ApiDoc注解手动标注。

5.2 用 @ApiDoc 注解补充推断不了的信息

JApiDocs 提供了一个@ApiDoc注解，用来补充它推断不出来的信息。比如：

@ApiDoc(result = UserVO.class, url = "/api/user/{id}", method = "GET") @GetMapping("/user/{id}") public UserVO getUser(@PathVariable Long id) { // ... }

result指定返回类型，url指定接口路径，method指定请求方法。当 JApiDocs 自动推断失败时，这些信息可以手动补上。

@ApiDoc还可以用在字段上：

public class UserVO { @ApiDoc(description = "用户ID，全局唯一") private Long userId; }

这样即使没有 Javadoc，文档里也会显示描述。

但要注意：@ApiDoc是 JApiDocs 特有的注解，加了之后代码就和 JApiDocs 绑定了。如果你以后想换回 Swagger 或者其他工具，这些注解就没用了。所以我的建议是：优先用 Javadoc 和规范的命名，只有在 JApiDocs 实在推断不出来的时候，才用@ApiDoc兜底。

5.3 忽略某些接口或字段

有些接口是内部用的，不想出现在文档里。JApiDocs 提供了忽略机制：

@ApiDoc(ignore = true) @GetMapping("/internal/health") public String healthCheck() { // ... }

字段级别也可以忽略：

public class UserVO { @ApiDoc(ignore = true) private String internalToken; }

还有一个全局配置：config.setAutoGenerate(false)，这样 JApiDocs 不会自动扫描所有接口，只生成你手动用@ApiDoc标注的接口。这种方式适合接口很多但只想暴露一部分的场景。

5.4 自定义模板与样式调整

JApiDocs 默认的 HTML 模板比较简洁，如果你想让文档看起来更符合团队风格，可以自定义模板。模板文件放在resources/templates下，JApiDocs 会优先使用自定义模板。

自定义模板的坑在于：模板变量是 JApiDocs 内部定义的，没有完整的文档说明。你需要看它的源码或者生成的默认模板，才能知道有哪些变量可用。我试过改模板，花了不少时间才搞明白变量结构。如果只是改改颜色和 logo，建议直接改生成的 CSS，比改模板简单。

另外，JApiDocs 生成的文档是纯静态的，没有搜索功能。如果接口很多，找起来很麻烦。解决办法是生成后用工具把 HTML 转成带搜索的格式，或者干脆把文档导入到其他支持搜索的平台。

6. 多模块与复杂项目结构的应对策略

6.1 多模块项目的扫描范围问题

前面提到过，JApiDocs 的setProjectPath只能指定一个目录，不会自动扫描子模块。如果你的项目结构是这样的：

parent-project/ ├── module-a/ │ └── src/main/java/ ├── module-b/ │ └── src/main/java/ └── module-c/ └── src/main/java/

那setProjectPath("parent-project")是没用的，JApiDocs 不会递归扫描module-a、module-b的源码。

解决办法有两种。第一种，每个模块单独生成文档，然后手动合并。这种方式工作量大，但可控性强。第二种，把projectPath设成每个模块的src/main/java目录，分别生成，然后用一个统一的入口页面链接过去。

我试过写一个脚本，遍历所有模块，对每个模块调一次Docs.buildHtmlDocs，输出到不同子目录，最后生成一个 index.html 汇总。这个方案稍微麻烦点，但一劳永逸。

6.2 接口分散在不同模块时的聚合

如果接口分散在多个模块，比如用户接口在user-module，订单接口在order-module，那生成文档时需要把它们的接口聚合到一起。

JApiDocs 本身不支持跨模块聚合。我的做法是：在每个模块里生成各自的文档，然后用 Nginx 或者 SpringBoot 的静态资源映射，把多个文档目录挂到同一个域名下的不同路径。比如/docs/user/、/docs/order/，然后在首页放一个导航。

另一种做法是：把所有接口的 Controller 类集中到一个模块里，只在这个模块生成文档。但这要求你的项目结构允许这样做，很多项目做不到。

6.3 与 CI/CD 流水线的集成

在 CI/CD 里自动生成文档，关键是确保构建环境能访问到源码。如果你的 CI 是拉取代码后编译，那源码就在工作目录里，setProjectPath设成相对路径就行。

但有个坑：CI 环境的工作目录可能和本地不一样。比如本地是/Users/xxx/project，CI 里是/builds/xxx/project。所以setProjectPath最好用相对路径或者环境变量，不要写死绝对路径。

还有一个坑：如果 CI 是多阶段构建，文档生成阶段可能没有完整的源码。比如你先用 Maven 打包，然后在另一个阶段生成文档，这时候源码可能已经被清理了。解决办法是把文档生成放在编译阶段，和编译一起做。

6.4 文档版本管理与历史归档

接口文档是需要版本管理的。每次发版，文档应该对应那个版本的接口。JApiDocs 生成的文档是静态的，你可以把每次生成的文档按版本号归档：

docs/ ├── v1.0/ ├── v1.1/ └── v2.0/

然后在入口页面提供版本切换。这样前端联调时，可以明确知道自己在看哪个版本的文档。

归档的另一个好处是：当接口发生不兼容变更时，可以对比新旧文档，快速定位差异。我试过用diff工具对比两个版本的 HTML，虽然不太直观，但能看出哪些接口变了。

7. 那些官方文档没写的实操心得

7.1 代码规范直接决定文档质量

用 JApiDocs 最大的体会是：文档质量不取决于工具，取决于你的代码写得怎么样。

字段命名规范、Javadoc 完整、类型清晰的代码，JApiDocs 生成的文档几乎不用改。反过来，如果代码里全是a、b、c这种命名，Javadoc 也不写，那生成的文档就是天书。

所以我的建议是：如果你打算用 JApiDocs，先把代码规范抓起来。至少做到这几点：

• 类名、方法名、字段名用完整的英文单词，不要用缩写
• 每个字段都写 Javadoc，说明含义和是否必填
• 枚举类型列出所有可选值
• 日期字段注明格式

这些规范不仅对 JApiDocs 有用，对代码可维护性也有好处。

7.2 生成时机与团队协作流程的配合

JApiDocs 什么时候生成文档，直接影响团队协作效率。

如果每次提交代码都自动生成，那文档永远是最新的，但 CI 时间会变长。如果手动生成，那可能忘记，导致文档滞后。

我的做法是：在 CI 里配置成“只有主分支合并时才生成文档”，这样既保证了文档更新，又不会每次提交都跑。开发分支上，开发者可以本地手动生成，自己看效果。

另外，文档生成后应该自动部署到内网服务器，让前端能随时访问。不要指望前端去拉代码自己生成，那太麻烦了。

7.3 常见报错与快速排查

用 JApiDocs 过程中遇到的一些典型报错：

报错一：Cannot find source file

原因：setProjectPath路径不对，或者源码目录结构不符合预期。

排查：确认路径下有没有.java文件，确认目录结构是标准的 Maven/Gradle 结构。

报错二：生成的文档是空的

原因：JApiDocs 没有找到任何带@Controller或@RestController的类。

排查：确认setAutoGenerate(true)，确认 Controller 类在扫描路径下，确认类上有正确的注解。

报错三：参数类型显示为Object

原因：泛型推断失败，或者类型太复杂。

排查：简化类型结构，或者用@ApiDoc手动指定。

报错四：中文乱码

原因：源码文件编码不是 UTF-8，或者 JApiDocs 读取时用了错误的编码。

排查：确保源码文件是 UTF-8 编码，在DocsConfig里设置setEncoding("UTF-8")。

7.4 性能优化：大项目生成慢怎么办

项目大了之后，JApiDocs 生成文档可能变慢。我试过一个有几百个接口的项目，生成一次要几十秒。

优化思路有几个：

• 减少扫描范围：只扫描 Controller 所在的包，不要扫描整个项目
• 关闭自动生成：用@ApiDoc手动标注需要生成文档的接口
• 增量生成：JApiDocs 不支持增量，但你可以自己写脚本，只对改动的模块生成

还有一个取巧的办法：把文档生成放在单独的线程里，不阻塞主流程。但这样需要处理好并发和资源竞争。

7.5 和其他文档工具的配合使用

JApiDocs 不是万能的，有些场景它搞不定，这时候可以和其他工具配合。

比如，对于 JApiDocs 推断不出来的复杂接口，可以用 Swagger 手动标注，然后两个文档并存。或者用 Postman 的文档功能，手动维护一部分接口。

我的经验是：不要指望一个工具解决所有问题。JApiDocs 覆盖 80% 的常规接口，剩下 20% 的复杂接口，用其他方式补充。这样整体效率最高。

8. 我的最终选型建议与适用场景判断

用了大半年 JApiDocs，我的整体评价是：它是一个“够用且省事”的工具，但不是“完美”的工具。

适合用 JApiDocs 的场景：

• 项目以标准 CRUD 接口为主，没有太多复杂嵌套和泛型
• 团队有基本的代码规范，字段命名和 Javadoc 比较完整
• 不想在代码里塞大量文档注解，追求代码干净
• 文档更新频率高，希望自动同步

不适合用 JApiDocs 的场景：

• 接口结构极其复杂，大量泛型嵌套和动态类型
• 团队代码规范差，字段命名随意，Javadoc 缺失
• 需要运行时动态生成文档（比如根据用户权限显示不同接口）
• 需要交互式调试功能（JApiDocs 只生成静态文档，不能像 Swagger 那样直接调接口）

如果让我给建议：新项目可以优先考虑 JApiDocs，配合良好的代码规范，能省下大量写文档的时间。老项目如果代码规范不好，迁移到 JApiDocs 可能反而更麻烦，不如继续用 Swagger 或者手动维护。

最后说一个我踩过的坑：JApiDocs 生成的文档默认没有鉴权，如果部署到公网，任何人都能访问。所以一定要放在内网，或者加一层权限控制。我试过用 Spring Security 保护文档路径，配置起来不复杂，但别忘了这一步。

文档工具终究是工具，核心还是代码本身。代码写清楚了，文档自然就清楚了。JApiDocs 只是帮你把代码里的信息提取出来，它不能替你写代码，也不能替你思考接口设计。把代码写好，剩下的交给工具，这才是正确的使用姿势。