Express

[TOC]

索引

~~express~~：

express()：()，
express.json()：()，
express.urlencoded()：()，
express.text()：()，
express.raw()：()，
express.Router()：()，
express.static()：()，

~~Application/Router~~：

~~Application~~：

app.locals：()，
app.listen()：()，
app.set()：()，
app.engine()：()，

~~Request~~：

req.method：()，
req.baseUrl：()，
req.originalUrl：()，
req.url：()，
req.protocol：()，
req.hostname：()，
req.path：()，
req.query：()，
req.params：()，
req.body：()，
req.cookies：()，
req.app：()，
req.res：()，

~~Response~~：

res.end()：()，用于结束当前响应流程，告知客户端响应已完成并发送最后的数据。
res.json()：(data)，用于向客户端发送JSON 格式的响应。
res.send()：()，
res.status()：(code)，用于设置 HTTP 响应的状态码。常与 res.send()、res.json() 等方法配合使用。
res.render()：()，
res.set()：()，
res.cookie()：()，
res.redirect()：()，

Express

express

express()@【

express()：()，

：``，
：``，
：``，
返回：
：``，

示例：

****：
js
1
****：
js
1
****：
js
1

~~核心特性~~：

****：
js
1
****：
js
1
****：
js
1

~~注意事项~~：

****：
js
1
****：
js
1
****：
js
1

json()@【

express.json()：()，

：``，
：``，
：``，
返回：
：``，

示例：

****：
js
1
****：
js
1
****：
js
1

~~核心特性~~：

****：
js
1
****：
js
1
****：
js
1

~~注意事项~~：

****：
js
1
****：
js
1
****：
js
1

urlencoded()@【

express.urlencoded()：()，

：``，
：``，
：``，
返回：
：``，

示例：

****：
js
1
****：
js
1
****：
js
1

~~核心特性~~：

****：
js
1
****：
js
1
****：
js
1

~~注意事项~~：

****：
js
1
****：
js
1
****：
js
1

text()【

express.text()：()，

：``，
：``，
：``，
返回：
：``，

示例：

****：
js
1
****：
js
1
****：
js
1

~~核心特性~~：

****：
js
1
****：
js
1
****：
js
1

~~注意事项~~：

****：
js
1
****：
js
1
****：
js
1

raw()【

express.raw()：()，

：``，
：``，
：``，
返回：
：``，

示例：

****：
js
1
****：
js
1
****：
js
1

~~核心特性~~：

****：
js
1
****：
js
1
****：
js
1

~~注意事项~~：

****：
js
1
****：
js
1
****：
js
1

Router()【

express.Router()：()，

：``，
：``，
：``，
返回：
：``，

示例：

****：
js
1
****：
js
1
****：
js
1

~~核心特性~~：

****：
js
1
****：
js
1
****：
js
1

~~注意事项~~：

****：
js
1
****：
js
1
****：
js
1

static()【

express.static()：()，

：``，
：``，
：``，
返回：
：``，

示例：

****：
js
1
****：
js
1
****：
js
1

~~核心特性~~：

****：
js
1
****：
js
1
****：
js
1

~~注意事项~~：

****：
js
1
****：
js
1
****：
js
1

Application/Router

use()【

app/router.use()：()，

：``，
：``，
：``，
返回：
：``，

示例：

****：
js
1
****：
js
1
****：
js
1

~~核心特性~~：

****：
js
1
****：
js
1
****：
js
1

~~注意事项~~：

****：
js
1
****：
js
1
****：
js
1

get()【

app/router.get()：()，

：``，
：``，
：``，
返回：
：``，

示例：

****：
js
1
****：
js
1
****：
js
1

~~核心特性~~：

****：
js
1
****：
js
1
****：
js
1

~~注意事项~~：

****：
js
1
****：
js
1
****：
js
1

post()【

app/router.post()：()，

：``，
：``，
：``，
返回：
：``，

示例：

****：
js
1
****：
js
1
****：
js
1

~~核心特性~~：

****：
js
1
****：
js
1
****：
js
1

~~注意事项~~：

****：
js
1
****：
js
1
****：
js
1

put()【

app/router.put()：()，

：``，
：``，
：``，
返回：
：``，

示例：

****：
js
1
****：
js
1
****：
js
1

~~核心特性~~：

****：
js
1
****：
js
1
****：
js
1

~~注意事项~~：

****：
js
1
****：
js
1
****：
js
1

delete()【

app/router.delete()：()，

：``，
：``，
：``，
返回：
：``，

示例：

****：
js
1
****：
js
1
****：
js
1

~~核心特性~~：

****：
js
1
****：
js
1
****：
js
1

~~注意事项~~：

****：
js
1
****：
js
1
****：
js
1

all()【

app/router.all()：()，

：``，
：``，
：``，
返回：
：``，

示例：

****：
js
1
****：
js
1
****：
js
1

~~核心特性~~：

****：
js
1
****：
js
1
****：
js
1

~~注意事项~~：

****：
js
1
****：
js
1
****：
js
1

route()【

app/router.route()：()，

：``，
：``，
：``，
返回：
：``，

示例：

****：
js
1
****：
js
1
****：
js
1

~~核心特性~~：

****：
js
1
****：
js
1
****：
js
1

~~注意事项~~：

****：
js
1
****：
js
1
****：
js
1

param()【

app/router.param()：()，

：``，
：``，
：``，
返回：
：``，

示例：

****：
js
1
****：
js
1
****：
js
1

~~核心特性~~：

****：
js
1
****：
js
1
****：
js
1

~~注意事项~~：

****：
js
1
****：
js
1
****：
js
1

Application

locals【

app.locals：()，

：``，
：``，
：``，
返回：
：``，

示例：

****：
js
1
****：
js
1
****：
js
1

~~核心特性~~：

****：
js
1
****：
js
1
****：
js
1

~~注意事项~~：

****：
js
1
****：
js
1
****：
js
1

listen()【

app.listen()：()，

：``，
：``，
：``，
返回：
：``，

示例：

****：
js
1
****：
js
1
****：
js
1

~~核心特性~~：

****：
js
1
****：
js
1
****：
js
1

~~注意事项~~：

****：
js
1
****：
js
1
****：
js
1

set()【

app.set()：()，

：``，
：``，
：``，
返回：
：``，

示例：

****：
js
1
****：
js
1
****：
js
1

~~核心特性~~：

****：
js
1
****：
js
1
****：
js
1

~~注意事项~~：

****：
js
1
****：
js
1
****：
js
1

engine()【

app.engine()：()，

：``，
：``，
：``，
返回：
：``，

示例：

****：
js
1
****：
js
1
****：
js
1

~~核心特性~~：

****：
js
1
****：
js
1
****：
js
1

~~注意事项~~：

****：
js
1
****：
js
1
****：
js
1

Request

method【

req.method：()，

：``，
：``，
：``，
返回：
：``，

示例：

****：
js
1
****：
js
1
****：
js
1

~~核心特性~~：

****：
js
1
****：
js
1
****：
js
1

~~注意事项~~：

****：
js
1
****：
js
1
****：
js
1

baseUrl【

req.baseUrl：()，

：``，
：``，
：``，
返回：
：``，

示例：

****：
js
1
****：
js
1
****：
js
1

~~核心特性~~：

****：
js
1
****：
js
1
****：
js
1

~~注意事项~~：

****：
js
1
****：
js
1
****：
js
1

originalUrl【

req.originalUrl：()，

：``，
：``，
：``，
返回：
：``，

示例：

****：
js
1
****：
js
1
****：
js
1

~~核心特性~~：

****：
js
1
****：
js
1
****：
js
1

~~注意事项~~：

****：
js
1
****：
js
1
****：
js
1

url【

req.url：()，

：``，
：``，
：``，
返回：
：``，

示例：

****：
js
1
****：
js
1
****：
js
1

~~核心特性~~：

****：
js
1
****：
js
1
****：
js
1

~~注意事项~~：

****：
js
1
****：
js
1
****：
js
1

protocol【

req.protocol：()，

：``，
：``，
：``，
返回：
：``，

示例：

****：
js
1
****：
js
1
****：
js
1

~~核心特性~~：

****：
js
1
****：
js
1
****：
js
1

~~注意事项~~：

****：
js
1
****：
js
1
****：
js
1

hostname【

req.hostname：()，

：``，
：``，
：``，
返回：
：``，

示例：

****：
js
1
****：
js
1
****：
js
1

~~核心特性~~：

****：
js
1
****：
js
1
****：
js
1

~~注意事项~~：

****：
js
1
****：
js
1
****：
js
1

path【

req.path：()，

：``，
：``，
：``，
返回：
：``，

示例：

****：
js
1
****：
js
1
****：
js
1

~~核心特性~~：

****：
js
1
****：
js
1
****：
js
1

~~注意事项~~：

****：
js
1
****：
js
1
****：
js
1

query【

req.query：()，

：``，
：``，
：``，
返回：
：``，

示例：

****：
js
1
****：
js
1
****：
js
1

~~核心特性~~：

****：
js
1
****：
js
1
****：
js
1

~~注意事项~~：

****：
js
1
****：
js
1
****：
js
1

params【

req.params：()，

：``，
：``，
：``，
返回：
：``，

示例：

****：
js
1
****：
js
1
****：
js
1

~~核心特性~~：

****：
js
1
****：
js
1
****：
js
1

~~注意事项~~：

****：
js
1
****：
js
1
****：
js
1

body【

req.body：()，

：``，
：``，
：``，
返回：
：``，

示例：

****：
js
1
****：
js
1
****：
js
1

~~核心特性~~：

****：
js
1
****：
js
1
****：
js
1

~~注意事项~~：

****：
js
1
****：
js
1
****：
js
1

cookies【

req.cookies：()，

：``，
：``，
：``，
返回：
：``，

示例：

****：
js
1
****：
js
1
****：
js
1

~~核心特性~~：

****：
js
1
****：
js
1
****：
js
1

~~注意事项~~：

****：
js
1
****：
js
1
****：
js
1

app【

req.app：()，

：``，
：``，
：``，
返回：
：``，

示例：

****：
js
1
****：
js
1
****：
js
1

~~核心特性~~：

****：
js
1
****：
js
1
****：
js
1

~~注意事项~~：

****：
js
1
****：
js
1
****：
js
1

res【

req.res：()，

：``，
：``，
：``，
返回：
：``，

示例：

****：
js
1
****：
js
1
****：
js
1

~~核心特性~~：

****：
js
1
****：
js
1
****：
js
1

~~注意事项~~：

****：
js
1
****：
js
1
****：
js
1

Response

end()

res.end()：()，用于结束当前响应流程，告知客户端响应已完成并发送最后的数据。

res.end()：()，无参数，仅结束响应。
res.end()：(data)，发送数据后结束响应。
res.end()：(data, encoding)，指定编码格式发送数据后结束响应。
- data?：string|buffer，要发送给客户端的最后数据。
- encoding?：string，默认：utf8，当 data 为字符串时，指定其编码格式（如 'utf8'、'base64' 等）。若 data 为 Buffer，此参数会被忽略。
返回：
res：Response，返回当前的响应对象（res 本身），支持链式调用（不常用）。

示例：

无参数：仅结束响应（客户端收到空响应）：

if (req.url === '/empty') {
    res.end(); 
    return;
}

带字符串数据：发送文本后结束响应：

if (req.url === '/text') {
    res.end('Hello, World!'); // 等价于 res.end('Hello, World!', 'utf8')
    return;
}

带 Buffer 和编码：发送二进制数据后结束响应：

if (req.url === '/buffer') {
    const buffer = Buffer.from('Binary data', 'utf8');
    res.end(buffer); // encoding 被忽略（因 data 是 Buffer）
    return;
}

~~核心特性~~：

必须调用 end() 终止响应：
无论是否发送数据，都必须调用 res.end() 来终止响应，否则客户端会一直等待（超时后报错）。
数据大小限制：
res.end() 适合发送少量 “收尾数据”，若需发送大量数据，应使用 res.write() 分块发送，最后用 res.end() 结束。
调用时机：
res.end() 是响应的 “最后一步”，调用后不能再对响应进行任何操作，否则会抛出错误。

json()

res.json()：(data)，用于向客户端发送JSON 格式的响应。

data：object|array|string|...，支持多种类型，要发送给客户端的最后数据。
返回：
res：Response，返回当前的响应对象（res 本身），支持链式调用。

示例：

链式调用（设置状态码后发送 JSON）：

app.get('/error', (req, res) => {
  // 先设置 404 状态码，再发送错误信息 JSON
  res.status(404).json({ code: 404, message: '资源不存在' });
});

~~核心特性~~：

data 参数支持的数据类型：

data 支持多种数据类型，Express 会自动将其序列化为 JSON 字符串：

参数类型	说明	序列化规则示例
`Object`	普通对象（键值对）	`{ name: '张三', age: 20 }` → `{"name":"张三","age":20}`
`Array`	数组	`[1, 2, 'a']` → `[1,2,"a"]`
`String`	字符串	`"hello"` → `"hello"`（JSON 字符串格式，带双引号）
`Number`	数字（整数、浮点数、NaN、Infinity）	`42` → `42`；`NaN` → `null`；`Infinity` → `null`（JSON 规范不支持 NaN/Infinity）
`Boolean`	布尔值	`true` → `true`；`false` → `false`
`null`	空值	`null` → `null`
`Date`	日期对象	`new Date('2023-01-01')` → `"2023-01-01T00:00:00.000Z"`（ISO 字符串）
`Buffer`	二进制缓冲区对象	转为 base64 字符串，如 `Buffer.from('test')` → `"dGVzdA=="`
其他特殊对象	如 `Map`、`Set` 等（需实现 `toJSON()` 方法，否则默认序列化结果可能不符合预期）	`new Map([['a', 1]])` → `{}`（默认无 `toJSON()` 方法，需手动处理）

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

// 1. 发送对象
app.get('/user', (req, res) => {
  res.json({ name: '张三', age: 20, isStudent: false });
});

// 2. 发送数组
app.get('/list', (req, res) => {
  res.json(['苹果', '香蕉', '橙子']);
});

// 3. 发送特殊值
app.get('/special', (req, res) => {
  res.json({
    date: new Date('2023-01-01'), // "2023-01-01T00:00:00.000Z"
    buffer: Buffer.from('hello'), // "aGVsbG8="
    nan: NaN, // null
    infinity: Infinity, // null
    nullVal: null // null
  });
});

app.listen(3000);

对比 res.send()：
res.send() 也可以发送 JSON 数据（当传入对象 / 数组时），但 res.json() 更明确且有以下差异：
- Content-Type 优先级：
  - res.json() 会强制将响应头 Content-Type 设置为 application/json，即使之前通过 res.set() 手动设置了其他类型。
  - 而 res.send() 会根据数据类型自动推断（如对象 / 数组设为 application/json，字符串设为 text/html）。
- 对非对象类型的处理：
  - res.json('hello') 会发送 JSON 字符串（带引号："hello"）。
  - 而 res.send('hello') 会发送纯文本（不带引号：hello）。
js
```
// res.json() 发送字符串 → JSON 格式
app.get('/json-str', (req, res) => {
  res.json('hello'); // 响应："hello"（Content-Type: application/json）
});

// res.send() 发送字符串 → 纯文本格式
app.get('/send-str', (req, res) => {
  res.send('hello'); // 响应：hello（Content-Type: text/html; charset=utf-8）
});
```
1
2
3
4
5
6
7
8
9
JSON 序列化限制：
res.json() 内部使用 JSON.stringify() 进行序列化，因此受限于 JSON 规范：
- 不支持循环引用（如 const a = {}; a.self = a; res.json(a) 会抛出错误）。
- 不支持 Function、Symbol 类型（会被忽略或转为 null）。
- NaN、Infinity 会被转为 null（如示例中所示）。

send()【

res.send()：()，

：``，
：``，
：``，
返回：
：``，

示例：

****：
js
1
****：
js
1
****：
js
1

~~核心特性~~：

****：
js
1
****：
js
1
****：
js
1

~~注意事项~~：

****：
js
1
****：
js
1
****：
js
1

status()

res.status()：(code)，用于设置 HTTP 响应的状态码。常与 res.send()、res.json() 等方法配合使用。

code：number，表示 HTTP 响应状态码。其值必须符合 HTTP 协议规范，有效范围为 100-599。
返回：
res：Response，返回当前的响应对象（res 本身），支持链式调用。

示例：

成功响应（200/201）：

// 200（OK）：请求成功
app.get('/success', (req, res) => {
  res.status(200).send('请求成功'); // 链式调用：设置状态码后发送文本
});

// 201（Created）：资源创建成功
app.post('/user', (req, res) => {
  res.status(201).json({ message: '用户创建成功', id: 123 }); // 发送 JSON 响应
});

客户端错误（400/404）：

// 400（Bad Request）：请求参数错误
app.post('/login', (req, res) => {
  if (!req.body.username) {
    res.status(400).json({ error: '用户名不能为空' });
  }
});

// 404（Not Found）：资源不存在
app.get('/nonexistent', (req, res) => {
  res.status(404).send('<h1>页面不存在</h1>'); // 发送 HTML 响应
});

服务器错误（500）：

// 500（Internal Server Error）：服务器内部错误
app.get('/error', (req, res) => {
  try {
    // 模拟错误
    throw new Error('数据库连接失败');
  } catch (err) {
    res.status(500).json({ error: '服务器内部错误', details: err.message });
  }
});

重定向（301/302）：

// 301（Moved Permanently）：永久重定向
app.get('/old-path', (req, res) => {
  res.status(301).redirect('/new-path'); // 结合 redirect() 方法
});

// 302（Found）：临时重定向（Express 中 redirect() 默认使用 302）
app.get('/temp', (req, res) => {
  res.status(302).redirect('/temp-new');
});

~~核心特性~~：

对比 res.sendStatus()：
- res.status(code)：仅设置状态码，不发送响应内容，需配合 send()、json() 等方法发送数据；
- res.sendStatus(code)：设置状态码的同时，自动发送该状态码对应的默认描述文本（如 res.sendStatus(404) 等价于 res.status(404).send('Not Found')）。
js
```
// res.status() + send()：自定义响应内容
res.status(404).send('自定义：页面不见了'); 

// res.sendStatus()：使用默认描述
res.sendStatus(404); // 响应体为 'Not Found'（默认文本）
```
1
2
3
4
5
状态码的默认值：
若未通过 res.status() 显式设置状态码，Express 会根据响应类型自动使用默认值：
- 成功响应（如 res.send('ok')）默认状态码为 200；
- 重定向（res.redirect()）默认状态码为 302；
- 错误响应（如未捕获的异常）可能默认使用 500。

render()【

res.render()：()，

：``，
：``，
：``，
返回：
：``，

示例：

****：
js
1
****：
js
1
****：
js
1

~~核心特性~~：

****：
js
1
****：
js
1
****：
js
1

~~注意事项~~：

****：
js
1
****：
js
1
****：
js
1

set()【

res.set()：()，

：``，
：``，
：``，
返回：
：``，

示例：

****：
js
1
****：
js
1
****：
js
1

~~核心特性~~：

****：
js
1
****：
js
1
****：
js
1

~~注意事项~~：

****：
js
1
****：
js
1
****：
js
1

res.cookie()：()，

：``，
：``，
：``，
返回：
：``，

示例：

****：
js
1
****：
js
1
****：
js
1

~~核心特性~~：

****：
js
1
****：
js
1
****：
js
1

~~注意事项~~：

****：
js
1
****：
js
1
****：
js
1

redirect()【

res.redirect()：()，

：``，
：``，
：``，
返回：
：``，

示例：

****：
js
1
****：
js
1
****：
js
1

~~核心特性~~：

****：
js
1
****：
js
1
****：
js
1

~~注意事项~~：

****：
js
1
****：
js
1
****：
js
1

Express ​

索引 ​

Express ​

express ​

express()@【 ​

json()@【 ​

urlencoded()@【 ​

text()【 ​

raw()【 ​

Router()【 ​

static()【 ​

Application/Router ​

use()【 ​

get()【 ​

post()【 ​

put()【 ​

delete()【 ​

all()【 ​

route()【 ​

param()【 ​

Application ​

locals【 ​

listen()【 ​

set()【 ​

engine()【 ​

Request ​

method【 ​

baseUrl【 ​

originalUrl【 ​

url【 ​

protocol【 ​

hostname【 ​

path【 ​

query【 ​

params【 ​

body【 ​

cookies【 ​

app【 ​

res【 ​

Response ​

end() ​

json() ​

send()【 ​

status() ​

render()【 ​

set()【 ​

cookie()【 ​

redirect()【 ​

Express

索引

Express

express

express()@【

json()@【

urlencoded()@【

text()【

raw()【

Router()【

static()【

Application/Router

use()【

get()【

post()【

put()【

delete()【

all()【

route()【

param()【

Application

locals【

listen()【

set()【

engine()【

Request

method【

baseUrl【

originalUrl【

url【

protocol【

hostname【

path【

query【

params【

body【

cookies【

app【

res【

Response

end()

json()

send()【

status()

render()【

set()【

cookie()【

redirect()【