使用JSDoc为RESTful API函数添加注解，可提升代码可读性和维护性。1. 通过@function、@param、@returns等标签描述接口用途、参数类型及返回值；2. 对POST请求标注请求体结构，明确必填与可选字段，并用@example提供调用示例；3. 针对PUT/DELETE请求，用@param标注路径参数，确保ID等关键信息清晰标识。配合IDE可实现自动提示与类型检查，增强开发效率。
在前端开发中，虽然 JavaScript 本身不支持类似 Java 的“注解”（Annotation），但可以通过 JSDoc 这样的文档注释规范来为 RESTful API 接口函数添加结构化说明，提升代码可读性和维护性。特别是在团队协作或封装请求方法时，使用 JSDoc 标注接口参数、返回值和用途非常实用。
1. 使用 JSDoc 注解描述 RESTful 接口函数
JSDoc 是一种广泛使用的 JavaScript 文档注释语法，可用于描述函数的参数、返回类型、方法用途等。针对 RESTful API 请求函数，可以这样书写：
/** * 获取用户列表（GET /api/users） * * @function getUserList * @param {string} [search=''] - 搜索关键词，用于过滤用户名 * @param {number} [page=1] - 当前页码 * @param {number} [limit=10] - 每页条数 * @returns {Promise<{ users: Array, total: number }>} 返回用户列表和总数 * @throws {Error} 请求失败时抛出错误 */ async function getUserList(search = '', page = 1, limit = 10) { const res = await fetch(`/api/users?search=${search}&page=${page}&limit=${limit}`); return await res.json(); }2. 标注 POST 类接口及请求体参数
对于创建资源的 POST 请求，需要特别说明请求体（body）的数据结构：
/** * 创建新用户（POST /api/users） * * @function createUser * @param {Object} userData - 用户数据对象 * @param {string} userData.name - 用户姓名，必填 * @param {string} userData.email - 邮箱地址，必须唯一 * @param {number} [userData.age] - 年龄，可选 * @param {string} [userData.phone] - 手机号，可选 * @returns {Promise<{ success: boolean, id: string }>} 创建成功返回ID * @example * createUser({ name: '张三', email: 'zhangsan@example.com' }) */ async function createUser(userData) { const res = await fetch('/api/users', { method: 'POST', body: JSON.stringify(userData), headers: { 'Content-Type': 'application/json' } }); return await res.json(); }3. 标注路径参数和 DELETE/PUT 请求
RESTful 中常见带路径参数的请求，如 PUT /api/users/:id，可用注解明确标识：
/** * 更新用户信息（PUT /api/users/{id}） * * @function updateUser * @param {string} id - 用户唯一标识符 * @param {Object} data - 要更新的字段 * @param {string} [data.name] - 新姓名 * @param {string} [data.email] - 新邮箱 * @returns {Promise<{ success: boolean }>} */ async function updateUser(id, data) { const res = await fetch(`/api/users/${id}`, { method: 'PUT', body: JSON.stringify(data), headers: { 'Content-Type': 'application/json' } }); return await res.json(); }
/**
- 删除用户（DELETE /api/users/{id}）
- @function deleteUser
- @param {string} id - 用户ID
- @returns {Promise<{ success: boolean }>}
*/
async function deleteUser(id) {
const res = await fetch(
/api/users/${id}, { method: 'DELETE' }); return await res.json(); }
基本上就这些。通过规范使用 JSDoc，可以让 API 接口更清晰，配合 IDE（如 VSCode）还能实现自动提示和类型检查，提高开发效率。
