FullStackOpen：phonebook app / back-end 要点总结

教程：FullStackOpen2021/Part 3 - 用NodeJS和Express写服务端程序

前端部分：FullStackOpen2021：phonebook app / front-end 要点总结

数据库部分：FullStackOpen：phonebook app / MongoDB 要点总结

App：React Phonebook App

1. 用 express 搭建 RESTful API

直接使用 Node 内置的 HTTP web 服务器实现服务器代码是可行的。但是，它很麻烦，且不适合较大规模的应用。

为了提供一个比内置的 HTTP 模块更友好的界面，许多库已经开发出来以简化使用 Node 作为服务器端开发。到目前为止，最受欢迎的库是 express。

初始化 express：

选择一个合适的目录，使用 npm init 命令创建一个新模板。
（可选）在 package.json 文件的 scripts 对象中添加 start 命令："start": "node index.js"
添加 express 库：npm install express。
代码的开头导入 express。这是一个function ，用于创建一个存储在 app 变量中的 express 应用。
将绑定的 HTTP 服务器分配给 app 变量，并监听发送到端口的 HTTP 请求。

const express = require("express");
const app = express();

...

const PORT = process.env.PORT || 3001;
app.listen(PORT, () => {
  // console.log(`Server running on port ${PORT}`);
});

接下来，开始定义路由（route）。

GET /

app.get("/", (req, res) => {
  res.send(
    `<h1>Phonebook API</h1>`
  );
});

第一个路由定义一个 event handler，用于处理对 / 路径发出的 HTTP GET 请求。

该 event handler 两个参数。第一个 req/request 参数包含 HTTP 请求的所有信息，第二个 res/response 参数用于定义请求的响应方式。

在代码中，请求是通过使用 res 对象的 send 方法使服务器通过发送 <h1>Phonebook API</h1> 字符串以 response 响应 HTTP 请求。由于参数是一个字符串，express 会自动将 Content-Type Header 的值设置为 text/html。响应的状态代码默认为200。

GET /api/persons

app.get("/api/persons", (req, res) => {
	...
  res.json(persons);
});

请求用 response 对象的 json 方法进行响应。调用该方法会将 persons 数组作为 JSON 格式的字符串进行传递。express 自动设置 Content-Type，其值为 application/json。

对于 express，会自动将数据转换为 JSON 格式。值得注意的是，JSON是一个字符串，不是 JavaScript 对象。

GET /api/persons/:id

app.get("/api/persons/:id", (req, res) => {
	const id = Number(req.params.id);

  ...

  if (person) {
    res.json(person);
  } else {
    res.status(404).end();
  }
});

可以使用冒号语法为 express 路由定义参数。

POST /api/persons

app.use(express.json()); // json-parser middleware

app.post("/api/persons", (req, res) => {
  const body = req.body;

  if (!body.name || !body.number) {
    return res.status(400).json({
      error: "name or number missing",
    });
  }

  if (persons.some((p) => p.name === body.name)) {
    return res.status(400).json({
      error: "name must be unique",
    });
  }

  const person = {
    name: body.name,
    number: body.number,
    id: generateId(),
  };

  ...

  res.json(person);
});

通过向地址 [root]/api/persons 发送一个 HTTP POST 请求，并以 JSON 格式在请求body中发送新 person 的所有信息，就可以添加一个 person。

为了正确访问 body 数据，需要添加 express 的 json-parser 中间件（middleware）。中间件是可用于处理请求和响应对象的函数。

DELETE /api/persons/:id

app.delete("/api/persons/:id", (req, res) => {
  ...

  res.status(204).end();
});

如果删除资源成功，这意味着该资源存在并被删除，应用状态码 204 no content 响应请求，返回没有数据的响应。

如果资源不存在，对于应该向 DELETE 请求返回 204 还是 404 状态代码并没有共识。为了简单起见，在这两种情况下都响应 204。

2. Same-origin policy and CORS

Cross-origin resource sharing (CORS) is a mechanism that allows restricted resources (e.g. fonts) on a web page to be requested from another domain outside the domain from which the first resource was served. A web page may freely embed cross-origin images, stylesheets, scripts, iframes, and videos. Certain “cross-domain” requests, notably Ajax requests, are forbidden by default by the same-origin security policy.

默认情况下，运行在浏览器应用的 JavaScript 代码只能与相同源的服务器通信。不同端口不具有相同的源。

可以通过使用 Node 的 cors 中间件来允许来自其他源的请求。

安装 cors 库：

npm install cors

使用中间件并允许来自所有来源的请求：

const cors = require('cors')

app.use(cors())

3. 部署前后端的生产环境

前端

因为部署后前端和后端都在同一个地址，所以可以声明 baseUrl 为 relative URL。

services/phonebook.js:

const baseUrl = "/api/persons";

const getAll = () => {
  const request = axios.get(baseUrl);
  ...
};

由于将后端地址更改为了一个相对 URL，在开发模式下，前端对后端的请求会发送到错误的地址。

如果项目是用 create-react-app 创建的，那么可以通过在前端 repository 的 package.json 文件中修改代理（proxy）来修复：

{
  "dependencies": {
    // ...
  },
  "scripts": {
    // ...
  },
  "proxy": "http://localhost:3001" //本地开发的后端端口
}

到目前为止，应用一直在开发模式中运行。在开发模式下，应用被配置为提供清晰的错误消息，立即向浏览器渲染代码更改等等。但当应用被部署至生产环境时时，必须创建一个生产构建或一个为生产而优化的应用版本。

使用 create-react-app 创建的应用可以使用命令 npm run build 创建。

这将创建一个名为 build 的目录，其中包含目录static。应用的 JavaScript 代码（包括所有应用依赖项的所有代码）将生成 minified 版本到 static 目录的一个文件中。

后端

为了让 express 显示 static content、页面 index.html 和它用来 fetch 的 JavaScript 等等，需要一个来自 express 的内置中间件，称为static：

app.use(express.static("build"));

另外，Heroku 会在环境变量的基础上配置应用端口，需确保 index.js 文件底部使用的端口定义正确：

const PORT = process.env.PORT || 3001;

Pipeline 是指通过不同的测试和质量检查将代码从开发人员的计算机转移到生产环境的自动化控制的方法。由于尚未将后端和前端代码放到同一 repository 中，前端部署和创建自动化的部署管道（deployment pipeline）较为复杂。

为了在没有额外手动工作的情况下创建前端的新的生产构建，可以在后端存储库的 package.json 中添加一些 npm-scripts:

{
  "scripts": {
     //...
    "build:ui": "rm -rf build && cd ../front-end/ && npm run build && cp -r build ../back-end",
    "deploy": "git push heroku main",
    "deploy:full": "npm run build:ui && git add . && git commit -m uibuild && git push && npm run deploy",    
    "logs:prod": "heroku logs -t"
  }
}

4. 部署应用到 Heroku

参考：Getting Started on Heroku with Node.js

创建并部署 Heroku 应用的基本流程：

注册 Heroku 账号。
下载并安装 Heroku。
确保 repository 中有正确的 package.json 和 .gitignore。
在 repository 根目录下运行 heroku create 命令，Heroku 会自动跳出 login 弹窗进行验证。
应用创建成功后，运行 git push heroku [branch_name] 命令，将本地 repository 部署到云端。

其他 Heroku 命令：

heroku open ：运行并在浏览器打开 Heroku 应用。
heroku logs --tail / heroku logs -t ：在terminal 显示 Heroku 应用的日志。
heroku ps ：查看有多少应用正在运行。
heroku ps:scale web=0 ：关闭所有应用。
heroku ps:scale web=1 ：重新运行应用。

5. 开发者工具

使用 nodemon 实时预览

nodemon 将监视启动 nodemon 的目录中的文件，如果任何文件发生更改，nodemon 将自动重启 node 应用。

npm install --save-dev nodemon

在 package.json 文件中为 nodemon 定义一个专用的 npm 脚本：

{
  ...
  "scripts": {
    "start": "node index.js",
    "dev": "nodemon index.js",
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  ...
}

在开发模式下使用命令启动服务器：

npm run dev

测试 RESTful API

可以使用 Postman 或 VS Code REST client。

使用 ESLint

Generically, lint or a linter is any tool that detects and flags errors in programming languages, including stylistic errors. The term lint-like behavior is sometimes applied to the process of flagging suspicious language usage. Lint-like tools generally perform static analysis of source code.

JavaScript 目前主要的静态分析工具是ESlint。

安装 ESlint 作为项目开发依赖项：

npm install eslint --save-dev

如果使用 VS Code 的 ESlint extension，也可以用全局安装：

npm install -g eslint

安装完成后，执行 eslint --init 命令，回答问题生成 ESlint 模板。

所有配置放在 .eslintrc.js 文件中：

module.exports = {
    "env": {
        'commonjs': true,
        "browser": true,
        "es2021": true
    },
    "extends": [
        "eslint:recommended",
    ],
    "parserOptions": {
        "ecmaFeatures": {
            "jsx": true
        },
        "ecmaVersion": 13,
        "sourceType": "module"
    },
    "rules": {
				...
    }
};

ESlint 有大量的规则（参考：Rules），可以通过编辑 .eslintrc.js 文件中的 rules 使用。

如果 IDE 有配置 ESlint extension，IDE 会自动持续运行 lint 程序，无需手动操作。

若有希望跳过 lint 检查的文件，可以创建一个 .eslintignore 文件，将应略过的文件加入。

手动使用 ESlint 检查和验证 index.js 文件：

eslint index.js

可以为 ESlint 创建一个单独的 npm 脚本：

{
  // ...
  "scripts": {
    "start": "node index.js",
    "dev": "nodemon index.js",
    // ...
    "lint": "eslint ."
  },
  // ...
}

1. 用 express 搭建 RESTful API#

GET /#

GET /api/persons#

GET /api/persons/:id#

POST /api/persons#

DELETE /api/persons/:id#

2. Same-origin policy and CORS#

3. 部署前后端的生产环境#

前端#

后端#

4. 部署应用到 Heroku#

5. 开发者工具#

使用 nodemon 实时预览#

测试 RESTful API#

使用 ESLint#