从头开始创建一个自动产生文档/类型安全的现代API(1) 创建项目/Eslint设置 - Bearalise

2025-02-18

Word count: 1.3k | Reading time≈ 5 min

背景

你是否曾经遇到过这样的 API 文档，其中每一个端点(endpoint)都被详细记录，你可以深入了解所有可能的响应类型，并查看它们的示例。同时，它们还包含模式（schemas），你甚至可以进入并测试这些特定的端点，实际运行并访问 API，设置请求头和其他细节。从这个文档开始，我将从头开始构建一个使用 Hono 的 API，并使用 OpenAPI 规范来全面记录我们的 API。因此，如果你访问 /doc，你会看到每一个端点都被记录在案。OpenAPI 实际上是一个工具生态系统，可以利用这些文档创建互动文档，或者生成客户端库及其他类似的东西。我一直在使用 Hono 构建应用程序，特别是我一直在使用他们的中间件 Zod OpenAPI，该中间件基本上允许你使用 Zod 来定义所有的模式（schemas），然后定义你的路由合约，并使用这些路由合约在定义请求处理程序时获得类型安全。所有这些最终都被转化为完全互动的文档。

技术实现简介

首先，我会使用NextJS和Hono搭建后台API。NextJS不用多介绍，它是一个用于构建全栈Web 应用的React 框架。Hono是一个小巧、简单且超快速的 Web 框架，构建在 Web 标准之上，号称可以在任何 JavaScript 运行时环境中运行，包括 Cloudflare Workers、Fastly Compute、Deno、Bun、Vercel、Netlify、AWS Lambda、Lambda@Edge 和 Node.js。

在设置 OpenAPI 时，我们也可以以一种可扩展的方式进行。例如，我们可以在一个地方设置所有的路由定义，然后在另一个地方设置所有的处理程序，但一切依然是类型安全的。我们实际上会导出这些路由定义的类型，并且可以使用它们来定义我们的请求处理程序。这样，我们可以在一个单独的文件中定义我们的处理程序，但仍然具有完整的类型安全性，这意味着我们准确知道对于这个特定的方法基于这个特定的路由我们应该响应什么。
除此之外，Hono 使得测试这些端点变得非常容易，因为他们有一个内置的测试客户端，本质上类似于 Hono RPC 客户端，可以在客户端代码中使用，并具有完全的类型安全性，但它也是一个非常好的测试体验。
此外，我们可以将其与 Drizzle 连接起来，Drizzle Zod 基本上允许我们定义我们的表，然后使用这些表定义来定义我们的 Zod 模式（schemas），然后我们可以直接在我们的 OpenAPI 定义中使用这些模式。因此，我们基本上有一个单一的事实来源，我们可以定义我们的表，得到我们的模式，然后在我们的路由定义中使用这些模式，从那时起，当我们定义处理程序时，所有类型都会流转。

其次，我使用了一些现成的库 stoker 和样板库 hono-open-api-starter 来减少代码量，当然你也可以直接自己实现。

创建项目

首先，使用命令创建测试项目：

bunx create-next-app@latest
bun add hono
bun add -D typescript @types/node
bun add @hono/node-server

Eslint设置

ESLint 是一个可配置的 JavaScript 代码检查工具。它可以帮助你发现并修复 JavaScript 代码中的问题。这些问题可以是潜在的运行时错误、未遵循最佳实践，或者是样式问题。ESLint 有很多配置，我们这里可以选用一个现成的：antfu/eslint-config,下面是实施步骤：

安装依赖

1	bun add i -D eslint @antfu/eslint-config

修改eslint.config.mjs

// eslint.config.mjs
import antfu from '@antfu/eslint-config'

export default antfu({
  type: "app",
  typescript: true,
  formatters: true,
  stylistic: {
    indent: 2,
    semi: true,
    quotes: "double",
  },
  ignores: ["**/migrations/*"],
}, {
  rules: {
    "no-console": ["warn"],
    "antfu/no-top-level-await": ["off"],
    "node/prefer-global/process": ["off"],
    "node/no-process-env": ["error"],
    "perfectionist/sort-imports": ["error", {
      tsconfigRootDir: ".",
    }],
    "unicorn/filename-case": ["error", {
      case: "kebabCase",
      ignore: ["README.md"],
    }],
  },
});

修改package.json

{
  "scripts": {
    "lint": "eslint .",
    "lint:fix": "eslint . --fix"
  }
}

执行 lint:fix

1	bun run lint:fix

命令会自动修正代码中不符合格式的问题。执行结果如下：

1
2
3

/home/richard/bunproject/opeonapidemo/app/api/index.ts
 11:1  warning  Unexpected console statement. Only these console methods are allowed: warn, error  no-console
 ✖ 1 problem (0 errors, 1 warning)

这个报警是指有console.log语句，后续我们会移除这个语句，当前报警是正常的。

作者：Bearalise
出处：从头开始创建一个自动产生文档/类型安全的现代API(1) 创建项目/Eslint设置 - Bearalise
版权：本文版权归作者所有
转载：欢迎转载，但未经作者同意，必须保留此段声明，必须在文章中给出原文链接。