Nuxt的接口设计和接口开发（一）

麻爪
700 阅读8分钟

Nuxt 的接口设计与接口开发

在 Nuxt 项目中，接口如同桥梁，横跨前端与后端，连接用户交互与数据处理逻辑，其设计与开发的优劣，直接关乎整个应用的性能、可维护性以及用户体验。

接口设计原则

  1. RESTful 设计理念：RESTful 架构风格为接口设计提供了清晰的蓝图。遵循它，接口 URL 应简洁直观，像是资源的定位符。例如，在一个博客系统里，获取所有文章的接口可以设计为 /api/articles，这里的 /api 前缀标识出接口路径，articles 明确指向文章资源，一目了然。同时，利用标准的 HTTP 方法，GET 用于获取数据、POST 提交新数据、PUT 更新已有数据、DELETE 执行删除操作，让前后端协作高度规范化。
  2. 版本控制：项目迭代升级难以避免，新功能上线或许会更改接口结构与数据格式。引入版本号能有效避免老版本客户端 “水土不服”。常见做法是把版本号加在 URL 前缀，比如 /v1/api/articles，后续即便接口逻辑大变，只要老版本客户端请求 /v1 下的接口，仍能稳定运行，为更新迭代留足缓冲空间。
  3. 输入输出规范：接口接收的参数需精准定义类型、范围与是否必填，防止前端传入非法数据。输出的数据格式同样关键，统一采用 JSON 格式既能被各类前端框架轻松解析，又便于维护。而且，返回数据要附带合适的状态码，200 代表成功，400 示意客户端错误，500 则说明后端出状况，辅助前端快速判断请求结果。

这些都是我们日常和后端联调接口十分常见的的接口

接口开发流程

  1. 环境搭建与依赖安装：基于之前搭建好的 MySQL 数据库环境，在 Nuxt 项目里开启接口开发之旅。首先要安装处理数据库连接的库，例如 mysql2 我们给项目 pnpm add mysql2。接着，创建专门用于存放接口代码的目录，通常放在 Nuxt 的 server 文件夹内，贴合 Nuxt 的服务端开发规范。
  2. 数据库连接封装：为了让接口代码简洁高效，先封装数据库连接函数。在 server/utils 目录新建 db.ts 文件：
import mysql from 'mysql2';

// 创建数据库连接
const connection = mysql.createConnection({
  host: '127.0.0.1',
  port: 3306,
  user: 'root',
  password: 'rootpassword',
  database: 'qrcodeinfo'
});

export function getDbConnection() {
  return connection;
}

这份代码创建并导出一个数据库连接函数，后续接口代码调用它就能快速连接数据库。

3. 接口逻辑实现：保存code信息的code.ts： 在 Nuxt 3 中，defineEventHandler、readBody 等工具极大地简化了接口开发流程：

  • defineEventHandler

    • 功能：defineEventHandler 是 Nuxt 3 用于定义服务端事件处理程序的核心函数。它接收一个异步函数作为参数，这个异步函数会处理传入的 HTTP 请求事件，并返回响应数据。本质上，它搭建起了前端请求与后端业务逻辑处理之间的桥梁。
    • 举例：
import { defineEventHandler } from 'nuxt3';

export default defineEventHandler(async (event) => {
    // 处理请求逻辑
    return { message: "这是一个简单响应" };
});

这段代码定义了一个基础的接口，任何前端发来的请求，都会触发这个匿名异步函数，最终返回一个包含简单消息的 JSON 对象作为响应。

  • readBody

    • 功能：readBody 用于读取 HTTP 请求中的请求体数据 。在前后端交互里，前端经常会通过 POST、PUT 这类请求方法发送数据给后端，readBody 就能轻松获取这些数据，而且它返回的是一个已经解析好的 JavaScript 对象，方便后续直接操作。
    • 举例：
import { defineEventHandler, readBody } from 'nuxt3';

export default defineEventHandler(async (event) => {
    const data = await readBody(event);
    console.log(data);
    return data;
});

同样如果我们使用get方法或者其他方法根据RESTful风格路由，我们会需要拿到query参数和params参数

获取 query 参数

query 参数是 URL 中 ? 符号之后的键值对，例如 https://example.com/api/user?id=1&name=test，这里的 id 和 name 就是 query 参数。可以使用 getQuery 函数来获取：

import { defineEventHandler, getQuery, send } from 'nuxt3';
import { getDbConnection } from '~/server/utils/db';

export default defineEventHandler(async (event) => {
    const connection = getDbConnection();
    try {
        const query = getQuery(event);
        const id = query.id;
        const name = query.name;

        // 数据库连接与操作
        await connection.promise().connect();
        const sql = `SELECT * FROM users WHERE id =? AND name =?`;
        const values = [id, name];
        const [results] = await connection.promise().query(sql, values);
        await connection.promise().end();

        return {
                  message: "数据查询成功",
                  result
                };
    } catch (error) {
        console.error('数据查询出错: ', error);
    throw createError({
      statusCode: 200,
      statusMessage: '数据查询出错',
    });
    }
});

获取 params 参数

params 参数通常用于 RESTful 风格的路由，例如路由定义为 /api/user/:id，这里的 :id 就是一个动态参数，也就是 params 参数。在 Nuxt 3 里，可以从 event.context.params 中获取：

import { defineEventHandler, send } from 'nuxt3';
import { getDbConnection } from '~/server/utils/db';

export default defineEventHandler(async (event) => {
    const connection = getDbConnection();
    try {
        const id = event.context.params.id;

        // 数据库连接与操作
        await connection.promise().connect();
        const sql = `SELECT * FROM users WHERE id =?`;
        const values = [id];
        const [results] = await connection.promise().query(sql, values);
        await connection.promise().end();

        return {
                  message: "数据查询成功",
                  result
                };
    } catch (error) {
      ```
   throw createError({
      statusCode: 200,
      statusMessage: '数据保存失败',
    });
   }
});

总结来说，query 参数用于常规的查询字符串传递，使用 getQuery 提取更方便；params 参数适合 RESTful 风格路由中的动态路径部分，直接从 event.context.params 获取即可。

假设前端使用 POST 方法发送一个 JSON 对象 { "key": "value" }，这段后端代码就能捕获并打印这个对象，随后把它原封不动返回给前端。

比如这里我们完成一个保存将来要生成链接信息的接口api/saveCodeInfo.ts


import { getDbConnection } from '../utils/db';
const connection = getDbConnection();

export default defineEventHandler(async (event) => {
  try {
    const data = await readBody(event);
    const { appid, title, android, ios } = data;
    const connection = getDbConnection();
    await connection.promise().connect();
    const sql = `INSERT INTO your_table (appid, title, android, ios) VALUES (?,?,?,?)`;
    const values = [appid, title, android, ios];
    const [result] = await connection.promise().query(sql, values);
    await connection.promise().end();
    return send(event, 200, {
      message: "数据保存成功",
      result
    });
  } catch (error) {
    console.error('数据保存出错: ', error);
    return sendError(event, createError({ statusCode: 500, statusMessage: "数据保存失败" }));
  }
});

然后就可以在前端的部分调用我们的接口了，按照我们之前文章的nuxt约定的原则，不需要专门导入接口，可以直接请求。

<template>
    <div>
        <form @submit.prevent="submitForm">
            <label for="appid">AppID:</label>
            <input type="text" id="appid" v-model="formData.appid" required>
            <label for="title">Title:</label>
            <input type="text" id="title" v-model="formData.title" required>
            <label for="android">Android:</label>
            <input type="text" id="android" v-model="formData.android" required>
            <label for="ios">iOS:</label>
            <input type="text" id="ios" v-model="formData.ios" required>
            <button type="submit">提交</button>
        </form>
    </div>
</template>

<script lang="ts" setup>
const formData = reactive({
    appid: '',
    title: '',
    android: '',
    ios: ''
});

const submitForm = async () => {
    try {
        const response = await useFetch('/api/saveCodeInfo', {
            method: 'POST',
            body: formData
        });
        if (response.data.value) {
            const { message } = response.data.value;
            console.log(message);
            // 可以在这里添加成功提示，比如弹窗告知用户数据保存成功
        }
    } catch (error) {
        console.error('请求接口出错:', error);
        // 同样可以添加失败提示，如弹窗显示错误信息
    }
};
</script>

Nuxt.js 服务端路由深度剖析

在 Nuxt.js 项目开发进程里，大家想必留意到了接口调用时的一些有趣现象，某些接口请求地址类似 /api/saveData，和前端路由、组件命名路由遵循着相近的约定式配置逻辑。要是不想让 API 路由带 “api” 前缀，把对应文件放在 /server/routes 目录下就行。下面，深入聊聊 Nuxt.js 服务端路由那些超实用的特性，涵盖动态参数获取、HTTP 方法适配，还有借助目录结构优化 API 空间规划。

动态参数路由

Nuxt.js 为开发者开启了方便之门，允许在 API 路由文件名里嵌入动态参数。打个比方，创建 server/routes/user/[userId].js 这么一个文件，就等于解锁了动态路由的新玩法。在对应的路由处理函数里，能够通过内置的上下文对象拿到动态参数。看下面这段代码：

// server/routes/user/[userId].js
export default (event) => {
    const userId = event.context.params.userId;
    return `User profile for ID: ${userId}`;
};

运行起来，当访问 /user/123 这样的链接时，服务器就会回应 User profile for ID: 123。为了让程序更稳健，避免因非法参数导致程序崩溃，还能用一些简单的类型校验逻辑，保证进来的数据符合预期，提升代码的可靠性。

HTTP 方法匹配

在应对不同 HTTP 方法这件事上，Nuxt.js 的路由设计得相当精妙。不用复杂的配置，只需在文件名后缀加上对应的方法标识就行。以下是几个直观示例：

// server/routes/book.get.js
export default () => {
    return "Retrieving book list";
};

// server/routes/book.post.js
export default () => {
    return "Adding a new book";
};

有了这样的设定，当向 /book 发出 GET 请求时，服务器会返回 Retrieving book list；要是发的是 POST 请求，得到的回应则是 Adding a new book 。要是用了别的 HTTP 方法，系统自然会给出 405 状态码，提示客户端这个请求不被接纳。

利用目录结构优化 API 命名空间

除了前面提到的要点，善用目录内的 index.[method].js 文件，能让 API 的组织架构清晰不少，这对条理化 API 命名空间特别有帮助。咱们用实例说明：

// server/routes/store/index.get.js
export default () => {
    return "Fetching store details";
};

// server/routes/store/index.post.js
export default () => {
    return "Updating store information";
};

// server/routes/store/product.get.js
export default () => {
    return "Getting product details from store";
};

采用这种目录加文件名的编排方式，API 的布局一下就明朗了。随着项目规模越来越大，不管是开发者独自排查问题，还是团队合作维护代码，都能更高效地锁定对应的路由逻辑，快速完成调整优化。

在 Nuxt.js 的世界里，精心雕琢的接口设计与高效的开发流程，配合上灵活多变的服务端路由特性，为构建高性能、易维护的应用程序奠定了坚实基础。从遵循 RESTful 规范来保障接口的清晰易懂，到借助 Nuxt 3 提供的实用工具简化开发步骤，再到利用路由层面的巧思优化整体架构，每一步都环环相扣。

关于nuxt服务端内容创建和接口请求还有更多细节内容我会在后面做一个小项目带领大家提到相关问题

avatar
文章
阅读
粉丝