实战RESTful API开发指南

RESTful API 实际应用

RESTful API 是一种基于 HTTP 协议的架构风格，广泛应用于现代 Web 开发中。其核心思想是通过统一的接口和资源标识（URI）实现客户端与服务器的交互。以下通过实际场景和代码示例展示其应用。

设计原则与核心概念

RESTful API 遵循六大原则：无状态、客户端-服务器分离、统一接口、缓存能力、分层系统和按需代码。资源通过 URI 标识，操作通过 HTTP 方法（GET、POST、PUT、DELETE）实现。

实际应用示例：用户管理系统

以下是一个基于 Node.js 和 Express 的 RESTful API 实现，模拟用户管理功能。

项目结构

src/
├── controllers/
│   └── userController.js
├── routes/
│   └── userRoutes.js
├── models/
│   └── User.js
└── app.js

模型定义（User.js）

使用 Mongoose 定义用户模型：

const mongoose = require('mongoose');
const UserSchema = new mongoose.Schema({
  name: { type: String, required: true },
  email: { type: String, required: true, unique: true },
  age: { type: Number }
});
module.exports = mongoose.model('User', UserSchema);

控制器逻辑（userController.js）

实现 CRUD 操作：

const User = require('../models/User');

exports.createUser = async (req, res) => {
  try {
    const user = new User(req.body);
    await user.save();
    res.status(201).json(user);
  } catch (error) {
    res.status(400).json({ error: error.message });
  }
};

exports.getUsers = async (req, res) => {
  const users = await User.find();
  res.json(users);
};

exports.getUserById = async (req, res) => {
  const user = await User.findById(req.params.id);
  if (!user) return res.status(404).json({ error: 'User not found' });
  res.json(user);
};

exports.updateUser = async (req, res) => {
  const user = await User.findByIdAndUpdate(req.params.id, req.body, { new: true });
  if (!user) return res.status(404).json({ error: 'User not found' });
  res.json(user);
};

exports.deleteUser = async (req, res) => {
  const user = await User.findByIdAndDelete(req.params.id);
  if (!user) return res.status(404).json({ error: 'User not found' });
  res.status(204).send();
};

路由配置（userRoutes.js）

定义 API 端点：

const express = require('express');
const router = express.Router();
const {
  createUser,
  getUsers,
  getUserById,
  updateUser,
  deleteUser
} = require('../controllers/userController');

router.post('/users', createUser);
router.get('/users', getUsers);
router.get('/users/:id', getUserById);
router.put('/users/:id', updateUser);
router.delete('/users/:id', deleteUser);

module.exports = router;

主程序（app.js）

集成中间件和路由：

const express = require('express');
const mongoose = require('mongoose');
const userRoutes = require('./routes/userRoutes');

const app = express();
app.use(express.json());

mongoose.connect('mongodb://localhost:27017/userdb', { 
  useNewUrlParser: true, 
  useUnifiedTopology: true 
});

app.use('/api', userRoutes);

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
});

测试 API

使用 cURL 或 Postman 测试接口：

创建用户

curl -X POST http://localhost:3000/api/users \
  -H "Content-Type: application/json" \
  -d '{"name":"Alice","email":"alice@example.com","age":25}'

获取用户列表

curl http://localhost:3000/api/users

更新用户

curl -X PUT http://localhost:3000/api/users/1 \
  -H "Content-Type: application/json" \
  -d '{"age":26}'

高级特性

分页与过滤

exports.getUsers = async (req, res) => {
  const { page = 1, limit = 10, name } = req.query;
  const query = {};
  if (name) query.name = { $regex: name, $options: 'i' };
  
  const users = await User.find(query)
    .limit(limit * 1)
    .skip((page - 1) * limit);
  
  res.json(users);
};

身份验证中间件

const authMiddleware = (req, res, next) => {
  const token = req.header('Authorization');
  if (!token) return res.status(401).json({ error: 'Access denied' });
  try {
    const verified = jwt.verify(token, process.env.JWT_SECRET);
    req.user = verified;
    next();
  } catch (error) {
    res.status(400).json({ error: 'Invalid token' });
  }
};

router.post('/users', authMiddleware, createUser);

响应格式标准化

统一响应结构：

const successResponse = (res, data, statusCode = 200) => {
  res.status(statusCode).json({
    success: true,
    data
  });
};

const errorResponse = (res, message, statusCode = 400) => {
  res.status(statusCode).json({
    success: false,
    error: message
  });
};

性能优化

缓存控制

router.get('/users', (req, res) => {
  res.set('Cache-Control', 'public, max-age=3600');
  getUsers(req, res);
});

数据验证

使用 Joi 库：

const Joi = require('joi');

const userSchema = Joi.object({
  name: Joi.string().required(),
  email: Joi.string().email().required(),
  age: Joi.number().min(0)
});

exports.createUser = async (req, res) => {
  const { error } = userSchema.validate(req.body);
  if (error) return errorResponse(res, error.details[0].message);
  // ...原有逻辑
};

版本控制

通过 URI 或 Header 实现：

// 路径版本控制
app.use('/api/v1', userRoutes);

// Header 版本控制
router.get('/users', (req, res) => {
  if (req.headers['accept-version'] === '2.0.0') {
    return getUsersV2(req, res);
  }
  getUsers(req, res);
});

错误处理中间件

全局错误捕获：

app.use((err, req, res, next) => {
  console.error(err.stack);
  errorResponse(res, 'Internal Server Error', 500);
});

文档生成

使用 Swagger UI：

const swaggerJsDoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');

const swaggerOptions = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'User API',
      version: '1.0.0'
    }
  },
  apis: ['./routes/*.js']
};

const swaggerSpec = swaggerJsDoc(swaggerOptions);
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

安全实践

HTTPS 强制

const helmet = require('helmet');
app.use(helmet());
app.use((req, res, next) => {
  if (!req.secure) {
    return res.redirect(`https://${req.headers.host}${req.url}`);
  }
  next();
});

速率限制

const rateLimit = require('express-rate-limit');
const limiter = rateLimit({
  windowMs: 15 * 60 * 1000,
  max: 100
});
app.use(limiter);

通过以上示例，展示了 RESTful API 在实际项目中的应用方式，涵盖基础 CRUD、性能优化、安全防护等关键场景。