JS虽无原生注解，但JSDoc通过特定注释实现接口描述功能，支持类型标注、参数说明与文档生成，配合TypeScript可提升类型推导与代码可读性，广泛应用于API定义、配置对象及团队协作场景。
JS 中并没有像 Java 那样的“注解”（Annotation）语法，因此所谓的“JS 注解”通常是指在代码中使用特定格式的注释（如 JSDoc），用于描述接口、类型、参数等信息。这些注释不仅提升代码可读性，还能被工具（如 TypeScript、ESLint、IDE）识别，实现类型检查和智能提示。
JSDoc 注解在接口定义中的作用
JSDoc 是 JavaScript 中广泛使用的文档注解规范。通过在函数、对象或变量前添加特定格式的注释，可以清晰地描述其用途、参数类型、返回值等。在定义接口（即对象结构或函数契约）时，JSDoc 能帮助开发者明确预期的数据结构。
- 描述函数接收的参数类型与含义
- 定义返回值的结构与类型
- 说明可能抛出的异常或边界情况
- 配合 TypeScript 使用时增强类型推导能力
常见 JSDoc 注解写法示例
以下是一些常用于接口描述的 JSDoc 标签及其用法：
@param：用于描述函数参数
@returns：说明函数返回值
@typedef：定义自定义类型，相当于接口定义
@property：描述对象中的某个属性
/\*\*
\* 用户登录接口请求数据结构
\* @typedef {Object} LoginRequest
\* @property {string} username - 用户名，不能为空
\* @property {string} password - 密码，需加密传输
\*/
/**
* 处理用户登录
* @param {LoginRequest} data - 登录请求数据
* @returns {boolean} 是否登录成功
*/
function handleLogin(data) {
// 实现逻辑
return true;
}
与 TypeScript 接口的对比与协作
TypeScript 提供了真正的接口语法（interface），但即使在 TS 中，JSDoc 依然有其价值。可以在 .ts 文件中同时使用 interface 和 JSDoc 来增强可读性。
/\*\*
\* 用户信息接口
\*/
interface User {
id: number;
name: string;
email?: string; // 可选
}
/**
* 获取用户信息
* @param {number} id - 用户唯一标识
* @returns {User} 用户对象
*/
function getUser(id) {
return { id, name: "张三", email: "zhang@example.com" };
}
这种写法既利用了 TypeScript 的静态类型检查，又通过 JSDoc 提供了语义化说明，便于团队协作和文档生成。
实际应用场景建议
在纯 JS 项目中，推荐使用 JSDoc 定义“接口”结构，尤其在涉及 API 请求/响应、配置对象、回调函数等场景。
- API 封装函数前添加 @typedef 描述入参出参
- 组件配置对象使用 @property 明确字段含义
- 配合 VS Code 等编辑器，获得自动补全和错误提示
- 使用工具如 jsdoc 或 TypeDoc 生成 HTML 文档
基本上就这些。虽然 JS 没有原生注解机制，但通过规范使用 JSDoc，完全可以实现类似“接口描述”的功能，提升代码质量与维护效率。
