第4章 后端API基础框架搭建

微信小程序电商实战（前后端分离架构）第4章后端API基础框架搭建本章目录01.项目初始化与环境准备02.RESTfulAPI设计规范03.后端分层架构实践04.数据库连接与模型定义05.中间件集成与异常处理06.测试接口开发与联调本章将带领大家从零开始搭建一个标准的后端服务框架，涵盖从环境配置到接口联调的全流程。为何需要后端API框架？前后端通信桥梁前端小程序与后端服务器数据交互的核心协议，构建高效、稳定的数据传输通道。代码组织与维护将业务逻辑、数据访问与请求处理解耦，使代码结构清晰，大幅降低维护与扩展成本。性能与安全保障内置中间件支持性能优化、安全认证与日志记录，构建稳健可靠的后端服务。标准化与团队协作遵循RESTful等统一设计规范，降低沟通成本，提升团队开发效率与协作体验。项目初始化与环境准备初始化项目1.创建文件夹：mkdirmini-program-api&&cdmini-program-api2.初始化配置：npminit-y安装核心依赖express：快速、极简的Web框架mongoose：MongoDB对象数据模型(ODM)cors：处理跨域资源共享问题morgan：HTTP请求日志中间件dotenv：加载环境变量配置推荐项目结构/src├──controllers#控制器层，处理请求逻辑├──models#数据模型层，与数据库交互├──routes#路由层，定义API接口├──services#服务层，处理业务逻辑├──utils#工具层，提供通用工具函数└──app.js#应用入口文件.env#环境变量配置文件package.json#项目依赖配置文件RESTfulAPI设计规范资源(Resource)GET(查询)POST(创建)PUT(更新)DELETE(删除)/api/users获取所有用户列表创建一个新用户批量更新用户删除所有用户/api/users/:id获取指定ID用户信息不常用更新指定ID用户信息删除指定ID用户核心设计原则资源标识使用URI唯一标识每个资源统一接口使用标准HTTP方法操作资源无状态请求包含所有必要信息，服务端不保存状态可缓存标记响应缓存性以提升性能分层系统通过分层架构简化系统设计后端分层架构实践分层架构通过职责分离，降低系统耦合度，提升代码复用性与可维护性。每一层专注于单一功能，实现高内聚低耦合。路由层(Routes)[请求入口]定义API接口URL与HTTP方法，接收请求并分发至控制器。控制器层(Controllers)[协调处理]接收路由请求，调用服务层处理逻辑，生成并返回响应结果。服务层(Services)[业务核心]封装核心业务逻辑，协调数据访问层完成数据交互与处理。数据访问层(Models)[数据交互]定义数据模型，提供数据库CRUD操作接口，屏蔽底层存储细节。工具层(Utils)[通用支撑]提供加密、验证、日期处理等通用工具函数，提升代码复用率。路由层实现创建路由文件:src/routes/user.routes.jsconstexpress=require('express');constrouter=express.Router();//引入对应的控制器constuserController=require('../controllers/user.controller');//定义用户相关的API接口router.get('/',userController.getAllUsers);router.get('/:id',userController.getUserById);router.post('/',userController.createUser);router.put('/:id',userController.updateUser);router.delete('/:id',userController.deleteUser);module.exports=router;在app.js中注册路由constuserRoutes=require('./routes/user.routes');//将用户路由挂载到/api/users路径下app.use('/api/users',userRoutes);核心作用：路由层负责定义API的URL路径和HTTP方法，作为请求的入口，将请求转发给对应的控制器处理。BackendDevelopment/Express.js/RoutingLayer控制器层实现src/controllers/user.controller.jsconstuserService=require('../services/user.service');exports.getAllUsers=async(req,res)=>{try{constusers=awaituserService.getAllUsers();res.status(200).json(users);}catch(error){res.status(500).json({message:error.message});}};exports.getUserById=async(req,res)=>{try{constuser=awaituserService.getUserById(req.params.id);if(!user)returnres.status(404).json({message:'用户不存在'});res.status(200).json(user);}catch(error){res.status(500).json({message:error.message});}};请求协调者接收路由请求，调用服务层处理业务逻辑，返回标准化响应。异常处理机制使用try-catch捕获服务层异常，统一返回500错误码及信息。状态码控制根据业务结果返回200(成功)、404(资源不存在)等HTTP状态码。设计原则：保持控制器逻辑简洁，仅负责参数校验、调用服务和响应结果，避免业务逻辑下沉。服务层实现src/services/user.service.jsconstUser=require('../models/user.model');exports.getAllUsers=async()=>{//调用数据模型查询数据库returnawaitUser.find();};exports.getUserById=async(id)=>{returnawaitUser.findById(id);};exports.createUser=async(userData)=>{constuser=newUser(userData);returnawaituser.save();};业务逻辑封装专注于核心业务逻辑处理，不直接处理HTTP请求，确保代码职责单一。数据交互层调用数据模型（Model）执行CRUD操作，作为控制器与数据库之间的桥梁。高复用与可测试服务方法可被多个控制器调用，便于单元测试，提升代码维护性。数据库连接与模型定义数据库连接(src/utils/db.js)constmongoose=require('mongoose');require('dotenv').config();//加载环境变量constconnectDB=async()=>{try{awaitmongoose.connect(process.env.MONGO_URI,{useNewUrlParser:true,useUnifiedTopology:true});console.log('MongoDB连接成功');}catch(error){console.error('MongoDB连接失败:',error.message);process.exit(1);}};module.exports=connectDB;数据模型定义(src/models/user.model.js)constmongoose=require('mongoose');//定义用户数据模型的结构（Schema）constuserSchema=newmongoose.Schema({name:{type:String,required:true},email:{type:String,required:true,unique:true},password:{type:String,required:true}},{timestamps:true});//创建并导出用户模型module.exports=mongoose.model('User',userSchema);核心要点：通过Mongoose建立数据库连接，利用Schema定义数据结构与验证规则，实现数据的规范化管理。中间件集成-CORS配置1.安装与配置示例$npminstallcorsconstcors=require('cors');//允许所有来源（开发环境）app.use(cors());//推荐：生产环境限制特定来源app.use(cors({origin:''}));浏览器安全策略限制跨域资源共享（CORS）是浏览器的一种安全机制，默认会阻止不同域名之间的请求。这是前后端分离架构中必须解决的问题。后端配置的必要性小程序与后端API通常运行在不同域名下。若不配置CORS，前端将无法正常获取数据，控制台会报跨域错误。中间件集成-日志中间件//1.引入并配置Morganconstmorgan=require('morgan');//开发环境：简洁输出到控制台app.use(morgan('dev'));//生产环境：输出到文件(combined格式)//constfs=require('fs');//constaccessLogStream=fs.createWriteStream('access.log');//app.use(morgan('combined',{stream:accessLogStream}));安装依赖：npminstallmorgan核心作用与价值请求记录：自动记录每个HTTP请求的详细信息（方法、URL、状态码等）。调试辅助：实时监控请求流向，快速定位接口报错或性能瓶颈。生产监控：支持将日志写入文件，便于后续分析服务器运行状态。全局异常处理app.js异常处理中间件实现//全局异常处理中间件，必须放在所有路由之后app.use((err,req,res,next)=>{console.error(err.stack);//打印错误堆栈res.status(500).json({message:'服务器内部错误',error:env==='prod'?'Error!':err.message});});防止服务器崩溃捕获所有未被处理的异常，避免进程意外退出，保障服务高可用性。统一错误响应格式向客户端返回标准的JSON错误信息，便于前端统一处理和展示。环境差异化反馈开发环境返回详细错误堆栈，生产环境返回通用提示，兼顾调试与安全。核心价值：提升系统稳定性，优化用户体验，规范后端错误处理机制。环境变量管理安装依赖npminstalldotenv配置.env文件#服务器端口PORT=5000#数据库连接MONGO_URI=mongodb://...#运行环境NODE_ENV=dev在app.js中加载require('dotenv').config();constPORT=process.env.PORT;app.listen(PORT,()=>{console.log(`Serveron${PORT}`);});敏感信息隔离将数据库密码、API密钥等敏感配置与代码分离，避免硬编码导致的安全风险。多环境灵活切换为开发、测试、生产环境配置不同的变量，无需修改代码即可快速切换运行环境。测试接口开发与联调1.创建测试路由(src/routes/test.routes.js)constexpress=require('express');constrouter=express.Router();//测试接口router.get('/',(req,res)=>{res.status(200).json({message:'后端API框架搭建成功！'});});2.在app.js中注册路由app.use('/api/test',require('./routes/test.routes'));启动服务器nodesrc/app.js访问测试接口http://localhost:5000/api/test验证响应结果{"message":"后端API框架搭建成功！"}常见问题排查-端口占用问题现象：启动服务器时控制台提示“Error:listenEADDRINUSE:addressalreadyinuse:::5000”，表示端口5000已被占用。Windows系统解决方案1.打开CMD，输入netstat-ano|findstr:5000找到PID。2.打开任务管理器，在“详细信息”中结束对应PID进程。macOS/Linux系统解决方案1.打开终端，输入lsof-i:5000找到PID。2.输入kill-9<PID>强制结束进程。替代方案：修改端口若不想结束占用程序，可在项目根目录的.env文件中修改PORT为其他未占用端口（如PORT=5001）。Tips:端口占用通常是由于进程未正常关闭或其他服务占用导致，请根据实际情况选择合适方案。常见问题排查-数据库连接失败问题现象：启动服务器时，控制台提示“MongoDB连接失败”，无法连接到数据库。检查MongoDB服务确保本地服务已启动，或远程服务器地址正确无误。检查连接字符串核对.env文件中的MONGO_URI，确认主机、端口及认证信息。检查网络连接远程连接时确保网络通畅，且27017端口已开放。检查数据库权限确认连接用户拥有访问