如何在 Node.js 中构建一个最小化 REST API

你需要为前端项目快速搭建一个后端。也许是原型开发、本地开发,或者一个简单的生产服务。搭建一个 Node.js REST API 不应该需要一周的配置时间。

本指南将带你使用现代 Node.js 和 Express 5 构建一个最小化 REST API。你将获得 JSON 解析、适当的错误处理和清晰的结构——所有这些只需约 80 行代码。

前置条件

开始之前,请确保你已具备:

• 安装了 Node.js 24 LTS 或更新版本(可从 Node.js 官方网站下载)
• 一个代码编辑器
• 基础的 JavaScript 知识

项目设置

创建一个新目录并初始化你的项目:

mkdir minimal-api
cd minimal-api
npm init -y

安装 Express 5:

npm install express

打开 package.json 并添加 "type": "module" 以启用 ESM 导入。你的文件应包含:

{
  "type": "module",
  "scripts": {
    "start": "node server.js"
  }
}

构建你的 Express 5 API

创建 server.js 文件并添加以下代码:

import express from 'express'

const app = express()
const PORT = process.env.PORT || 3000

// Built-in JSON parsing middleware
app.use(express.json())

// In-memory data store
let items = [
  { id: 1, name: 'First item' },
  { id: 2, name: 'Second item' }
]

let nextId = 3

// GET all items
app.get('/api/items', (req, res) => {
  res.json({ data: items })
})

// GET single item
app.get('/api/items/:id', (req, res) => {
  const item = items.find(i => i.id === parseInt(req.params.id))
  if (!item) {
    return res.status(404).json({ error: 'Item not found' })
  }
  res.json({ data: item })
})

// POST new item
app.post('/api/items', (req, res) => {
  const { name } = req.body
  if (!name) {
    return res.status(400).json({ error: 'Name is required' })
  }
  const newItem = { id: nextId++, name }
  items.push(newItem)
  res.status(201).json({ data: newItem })
})

// DELETE item
app.delete('/api/items/:id', (req, res) => {
  const index = items.findIndex(i => i.id === parseInt(req.params.id))
  if (index === -1) {
    return res.status(404).json({ error: 'Item not found' })
  }
  items.splice(index, 1)
  res.status(204).send()
})

// 404 handler for undefined routes
app.use((req, res) => {
  res.status(404).json({ error: 'Route not found' })
})

// Error handling middleware
app.use((err, req, res, next) => {
  console.error(err.stack)
  res.status(500).json({ error: 'Internal server error' })
})

app.listen(PORT, () => {
  console.log(`Server running on http://localhost:${PORT}`)
})

启动你的服务器:

npm start

理解 JavaScript 后端 API 结构

这个最小化的 REST API Node 设置涵盖了以下要点:

JSON 解析: Express 5 将 express.json() 作为内置中间件。无需外部包(参见 Express API 文档)。

一致的响应: 每个端点都返回带有 data 或 error 属性的 JSON。这种可预测性帮助前端代码统一处理响应。

HTTP 状态码: API 使用适当的状态码——200 表示成功,201 表示创建资源,204 表示成功删除,400 表示错误请求,404 表示资源未找到,500 表示服务器错误。

错误处理: 通用错误中间件可防止未处理的路由错误导致服务器崩溃。

测试你的端点

使用 curl 或任何 HTTP 客户端:

# Get all items
curl http://localhost:3000/api/items

# Get single item
curl http://localhost:3000/api/items/1

# Create item
curl -X POST http://localhost:3000/api/items \
  -H "Content-Type: application/json" \
  -d '{"name": "New item"}'

# Delete item
curl -X DELETE http://localhost:3000/api/items/1

本指南未包含的内容

本指南有意跳过了数据库、身份验证和复杂验证。这些对于生产系统很重要,但在学习基础知识或快速搭建原型时会增加干扰。

当你准备扩展时,可以考虑添加:

• 使用 Zod 等库进行输入验证
• 使用环境变量进行配置
• 连接数据库以实现持久化

总结

你现在拥有了一个使用 Express 5 在 Node.js 中运行的最小化 REST API。这里的模式——一致的 JSON 响应、适当的状态码和集中式错误处理——随着 API 的增长能够很好地扩展。从这个基础开始,然后仅在项目需要时添加复杂性。

常见问题

Express 4 和 Express 5 有什么区别?

Express 5 为路由处理器提供了原生 Promise 支持,这意味着返回或抛出的被拒绝的 Promise 会自动触发错误中间件。它还移除了已弃用的方法并改进了路径匹配。核心 API 保持相似,因此对于大多数项目来说,从 Express 4 迁移是简单直接的。

为什么使用内存数组而不是数据库?

内存存储使示例专注于 API 结构而不是数据库配置。它非常适合原型开发和学习。对于生产环境,请将数组替换为 PostgreSQL 或 MongoDB 等数据库,以便在服务器重启后持久化数据。

如何为此 API 添加 CORS 支持?

使用 npm install cors 安装 cors 包,然后导入它并在路由之前添加 app.use(cors())。你可以传递选项来限制哪些源可以访问你的 API。当前端运行在与后端不同的域或端口时,这是必需的。

我可以将此结构用于生产 API 吗?

此结构提供了坚实的基础,但生产使用需要添加更多功能。需要添加输入验证、身份验证、速率限制、日志记录和适当的数据库。这里展示的一致响应格式和错误处理模式在添加这些功能时能够很好地扩展。