Coursera 笔记

Module 03 · Express Web Application FrameworkExpress Web 应用框架

Express Best PracticesExpress 最佳实践

Coursera ↗

🎥 视频目标：
在观看本视频后，您将能够：

  • 描述构建 Express 应用和 API 的文件夹结构约定。
  • 识别构建 Express 应用和 API 时常用的最佳实践。

Express 应用文件夹结构

在许多 Web 框架中，如 Ruby on Rails、.NET 和 Django，通常会有预定义的目录结构用于存储文件。而在 Express 中，并没有强制要求使用特定的目录结构。不过，提前定义目录结构通常是一个好主意，特别是在应用规模扩展时，合理的文件夹结构能够帮助维护项目的整洁。

常见文件夹结构

在项目文件夹中，通常使用以下目录来存储文件：

文件夹 说明
node_modules 包含应用的模块和包，执行 npm install 命令后自动生成。
config 配置文件夹，包含数据库连接配置、环境变量文件、外部服务的 API 密钥等。
models 包含数据模型文件，定义数据存储类型（如关系型或非关系型数据库），使用 ORM（对象关系映射）库来定义。
routes 用于定义各个实体的路由，通常会为每种资源类型创建一个单独的文件。
views 存放模板文件，动态生成 HTML、CSS 和 JavaScript，用于发送给客户端，方便创建用户特定的界面。
public 包含所有静态内容，如图片、CSS 和 JavaScript。通常会为每种类型的内容创建子文件夹。

项目文件

项目文件夹中通常还包括以下文件：

  • app.js：应用的主要配置文件。
  • routes.js：统一管理所有路由，导入并导出路由模块，作为应用的入口。
  • package.json：包含用于管理项目依赖关系的元数据。

API 文件夹结构

对于 API 项目，文件夹结构与常规项目类似，但不需要 views 和 public 文件夹，因此 API 文件夹结构通常是这样的：

  • node_modules
  • config
  • models
  • routes

文件：

  • app.js
  • routes.js
  • package.json

命名 API 路由

在命名 API 路由时，应该使用名词作为资源标识符。以下是使用 “employee”（员工）作为路由的 HTTP 示例：

HTTP 方法 路由示例 描述
POST /employees 创建员工信息
GET /employees/{id} 获取指定员工信息
PATCH /employees/{id} 更新指定员工信息
DELETE /employees/{id} 删除指定员工信息

HTTP 状态码使用规范

  • 200 系列：请求成功。
  • 300 系列：资源已移动。
  • 400 系列：客户端错误。
  • 500 系列：服务器端错误。

黑箱测试 REST API

黑箱测试意味着在不查看代码内部结构的情况下测试系统。Mocha 是一个运行在 Node.js 上的 JavaScript 测试框架，SuperTest 是其一个简单模块，可以用来测试 HTTP 请求，正好适用于黑箱测试 REST API。

安装 SuperTest：

npm install supertest --save-dev

使用 SuperTest 测试 REST API 时，无需关心内部实现，只需关注输入与输出。

基于 JWT 的无状态认证

当 API 需要认证时，最佳实践是使用基于 JSON Web Token（JWT）的无状态认证。由于 REST API 必须是无状态的，因此认证信息也应存储在客户端，而不是服务器端。

JWT 验证用户身份，通过向客户端提供大部分会话信息（如用户属性）来实现。

良好的 API 文档

创建适当的 API 文档是至关重要的，因为 API 的目的是让他人能够使用它。良好的文档有助于其他开发者理解和使用您的 Node.js REST API。

常用开源项目：

  • API Blueprint：可以在 apiary.io 上找到，适用于创建 API 文档。
  • Swagger：可以在 swagger.io 上找到，广泛用于 RESTful API 文档生成。

其他开发技巧

  • 初始化 Node.js 项目：使用 npm init 命令初始化项目。
  • 安装依赖时使用推荐参数：使用 npm install --save 或 --save-dev 来确保在应用迁移到不同平台时，正确的依赖项会随之安装。
  • 避免推送 node_modules：不要将 node_modules 文件夹推送到 Git 仓库。
  • 使用推荐的命名约定：
    • 文件名全部小写。
    • 变量使用驼峰命名法（camelCase）。
    • npm 模块使用小写，单词之间用短横线（-）分隔。
    • 在使用 require 导入模块时，模块名称使用驼峰命名法。

总结

在本视频中，您学习了如何在 Express.js 应用和 API 中使用合理的目录结构，其中包括 node_modules、config、models 和 routes 文件夹。开发 RESTful API 时的最佳实践包括：

  • 使用名词作为资源标识符。
  • 正确使用 HTTP 状态码。
  • 使用 SuperTest 进行黑箱测试。
  • 使用基于 JWT 的无状态认证。
  • 提供良好的 API 文档。

另外，其他有用的提示包括：遵循大小写命名规范，按照推荐使用 npm，使用配置文件存储变量，并将具有相似功能的路由分组到独立文件中。