# koa2-api **Repository Path**: gitee_store/koa2-api ## Basic Information - **Project Name**: koa2-api - **Description**: 该项目是一个基于koa2框架开发的项目。 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2024-04-09 - **Last Updated**: 2025-09-08 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 一.项目的初始化 ## 1.关于 - 这是一个关于 Node + Koa2 从零搭建通用 API 服务的项目 - 可使用 [Typora](https://typoraio.cn/) 软件编辑该 readme.md 说明文件 - Koa 是一个基于 Node.js 平台的下一代 Web 开发框架，它是 Express 框架的升级版。Koa 框架采用了 ES6 Generator 函数的编程风 格，使得异步代码的编写更加简单和直观。Koa 框架的设计理念是“中间件优先”，它提供了一种更加灵活和可控的中间件机制，使得开 发者可以轻松地编写出高效、安全、可维护的 Web 应用程序。 - Sequelize 是一个基于 Node.js、支持 Promise 语法的 ORM（对象关系映射）工具，能让开发者通过 JavaScript（或 TypeScript） 代码，便捷、规范化地操作 MySQL、PostgreSQL、SQL Server 等主流关系型数据库。它的核心作用是将 JavaScript 中的 “对象” 与 数据库中的 “表 / 记录” 建立映射关系 —— 开发者无需编写原生 SQL 语句，只需调用 Sequelize 提供的 JavaScript 方法（如 findAll 查数据、create 新增数据），即可完成数据库的增删改查；同时还内置数据校验、表关联管理、事务支持等能力，进一步降 低数据库操作的复杂度，提升开发效率。 ## 2.学习来源 - 学习于哔哩哔哩教程视频 - 学习地址 ： - 当前学习位置: 07:45 - Squelize 官方文档：[Squelize 官方文档](https://sequelize.org/docs/v6/getting-started/) - Squelize 中文文档：[Squelize 中文文档](https://www.sequelize.cn/) ## 3.项目环境 - node: v16.20.2 ## 4.npm 初始化 ```bash npm init -y ``` 使用上面命令生成 package.json 文件，该文件的作用： - 记录项目的依赖 ## 5.git 初始化 ```bash git init ``` 使用上面命令生成'.git'隐藏文件夹，该文件夹是 git 的本地仓库 ## 6.创建 readme.md 文件 - 记录项目详情、使用等相关说明 # 二.搭建项目 ## 1.安装 koa 框架 ```bash npm install -S koa ``` ## 2.编写最基本的 app 创建 src/main.js，编写下面代码 ```js const Koa = require("koa"); const app = new Koa(); const port = 3000; app.use((ctx, next) => { ctx.body = "hello"; }); app.listen(port, () => { console.log(`Server is running on： http://localhost:${port}`); }); ``` ## 3.测试 在终端，使用命令 node src/main.js 运行项目（使用这种方式是运行在常驻内存的，这时候修改项目源代码浏览器内容不会更新，除非 重新执行该运行命令） # 三.项目的基本优化 ## 1.自动重启服务 安装 nodemon 工具，使用该工具后，修改源码（后缀名为 js,mjs,cjs,json 的文件）保存后会自动重启服务 ```bash npm install -D nodemon ``` 执行 npm run dev 启动服务 ## 2.读取配置文件 在真实项目中，不要将 main.js 里的端口号写死，可以安装使用 dotenv 依赖，dotenv 会读取根目录中的.env 配置文件中的键值对并 将其写入到 process.env 环境变量中，我们再统一通过 process.env 环境变量获取端口号即可 安装 dotenv，读取根目录中的.env 配置文件，将配置写到 process.env 中 ```bash npm install -D dotenv ``` # 四.添加路由 路由：根据不同的 URL，调用对应的处理函数 ## 1.安装 koa-router ```bash npm install -S koa-router ``` ## 2.使用步骤 1. 导入包 2. 实例化对象 3. 编写路由 4. 注册中间件 # 五.目录结构优化 在该后端项目分层架构中，各层的职责： - 路由（Router）层：请求往哪走（定义路由规则，分发请求到对应控制器） - 中间件层：能不能执行（前置校验，如权限、参数、资源存在性） - 控制器（Controller）层：执行什么（接收请求，调用对应的 Service，返回响应） - 服务（Service）层：如何执行（实现具体业务逻辑，协调数据操作，处理事务） - 模型（Model）层：数据是什么（定义数据结构，提供基础 CRUD 操作） ## 1.将 http 服务和 app 业务拆分 将 main.js 里的业务相关的代码抽取到 app/index.js，改写 main.js ### 1.1 HTTP 方法语义语义 HTTP 方法语义规范补充： 1. GET: - 语义：获取资源（只读操作） - 特点：无请求体，参数通过 URL 传递；具有幂等性（多次调用结果一致） - 适用场景：查询数据（如获取购物车列表、商品详情） - 注意：不应用于修改数据，浏览器可能缓存 GET 请求 2. POST: - 语义：创建新资源（或执行非幂等操作） - 特点：请求数据放在请求体；不保证幂等性（多次调用可能创建多个资源） - 适用场景：新增数据（如添加商品到购物车、创建订单） 3. PUT: - 语义：全量更新资源（替换整个资源） - 特点：需提供资源的完整字段（缺失字段可能被清空）；具有幂等性 - 适用场景：完整替换资源（如覆盖更新用户信息、全量修改订单信息） 4. PATCH: - 语义：部分更新资源（仅修改指定字段） - 特点：仅需传递需要修改的字段；具有幂等性 - 适用场景：局部修改（如更新购物车商品数量、修改订单状态） 5. DELETE: - 语义：删除资源 - 特点：通常通过 URL 指定资源 ID；具有幂等性（多次删除结果一致） - 适用场景：移除数据（如从购物车删除商品、取消订单） 幂等性说明：指多次调用同一接口，不会产生不同的副作用（如创建多个资源）。 GET/PUT/PATCH/DELETE 应保证幂等性，POST 通常不保证。 ## 2.将路由和控制器拆分 - 路由(router)：解析 URL，分布给控制器对应的方法 - 控制器(controller)：专注于 “执行什么”（核心业务逻辑），不同的控制器处理不同的业务 # 六.解析 body(请求体) ## 1.安装 koa-body ```bash npm install -S koa-body ``` ## 2.注册 koa-body 中间件 在所有路由处理之前注册 koa-body 中间件。 ## 3.解析请求数据 注册 koa-body 中间件后，直接使用 ctx.request.body 即可获取到请求数据。 ## 4.拆分 service 层 改写 controller 层，将操作数据库的步骤从 controller 层抽离出去作为 service 层，service 层主要是做数据库处理的。 # 七.数据库的操作 Sequelize 是一个基于 promise 的 Node.js ORM 数据库工具。 Sequelize 工具地址：。 ORM：对象关系映射 - 数据表映射（对应）一个类 - 数据表中的数据行（记录）对应一个对象 - 数据表的字段对应对象的属性 - 数据表的操作对应对象的方法 安装 sequelize ```bash npm install --save sequelize ``` 此外，还必须手动为所选数据库安装驱动程序： ```bash # 选择以下之一: npm install --save pg pg-hstore # Postgres npm install --save mysql2 # 该项目选择 mysql2 作为数据库 npm install --save mariadb npm install --save sqlite3 npm install --save tedious # Microsoft SQL Server npm install --save oracledb # Oracle Database ``` 连接数据库 编写配置文件，编写与连接数据库相关的信息 # 八.创建模型 拆分出 Model 层（模型是代表数据库中表的抽象）。 注意：首次运行项目需要去 model 目录把里面所有文件的 xxx.sync(...) 代码的注释放开（不放开不会创建表） # 九.添加数据入库 添加数据前进行合理性判断和合法性判断，操作数据库，设置响应结果。 # 十.错误处理 记录错误日志。 对请求的错误进行统一处理，返回相应的错误提示码、错误信息等。 错误提示码。第一位：前台错误 2，后台错误 1；第二和第三位：报错的具体模块（用户模块|商品模块...）；第四和第五位：错误的详 细编号。 # 十一.拆分中间件 中间件：专注于 “能不能执行”（前置条件校验） 将用户信息合法性校验、用户合理性校验拆分成中间件，在用户请求命中路由后先交由中间件处理 # 十二.加密 在将密码保存到数据库之前，要对密码进行加密处理 安装 bcryptjs 加密库（bcryptjs 加密库是 bcrypt 加密库的优化版，已经经过 C++ 编译过的，不需要再像 bcrypt 加密库那样另外安 装其他依赖） ```bash npm i -S bcryptjs ``` 加盐，在原有密码的基础上加上随机字符，再对加盐过的字符串进行一次编码，这就是加一次盐。 经过加一次盐后会得到一个结果，然后通过一定的算法再进行第二次加盐，这是加盐加密。 如果对密码安全要求不太高可以直接使用 md5 加密。 # 十三.登录验证 # 十四.用户的验证 登录成功后，给用户颁发一个令牌 token，用户在以后的每一次请求中携带这个令牌，这个令牌的作用是让服务端确认用户身份的。使用 JWT 生成 token。 JWT：Json Web Token JWT 的构成： - header(头部)：包含两部分信息，一个是声明类型，一个是声名的加密算法 - payload(载荷)：有效信息 - signature(签名)：用于验证 token 的有效性 安装 jsonwebtoken ```bash npm i -S jsonwebtoken ``` # 十五.上传文件 安装 koa-static 依赖，用于处理静态资源（把某一个目录设置成静态资源文件夹，当我们请求静态资源文件夹里的文件的时候，就会到 对应文件夹里找）。 ```bash npm i -S koa-static ```