如何在 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 的增长能够很好地扩展。从这个基础开始,然后仅在项目需要时添加复杂性。

常见问题

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.