Node.js 注释规范模板（AI 可用标准版）

/**
 * @file 文件名.js
 * @description 文件功能简介
 * @author 作者名
 * @date YYYY-MM-DD
 * @version 版本号
 * @license 许可信息（可选）
 */

/**
 * @file userController.js
 * @description 用户模块控制器，处理注册、登录及信息管理
 * @author ZhangYaLong
 * @date 2026-03-29
 * @version 1.0.0
 */

/**
 * 类名/模块名
 * 功能描述
 * 注意事项或使用说明
 */
class ClassName {}

/**
 * UserService 类
 * 提供用户增删改查及认证功能
 * 注意：所有方法均异步执行
 */
class UserService {}

/**
 * 功能描述
 * @async (可选，异步函数)
 * @param {类型} 参数名 - 参数说明
 * @param {类型} 参数名.prop - 对象属性说明
 * @returns {类型} 返回值说明
 * @throws {Error} 异常说明
 * @deprecated (可选，废弃方法)
 * @example (可选，使用示例)
 */

/**
 * 根据用户ID获取用户信息
 * @async
 * @param {number} userId - 用户ID
 * @returns {Promise<Object>} 用户信息对象
 * @throws {Error} 当用户不存在时抛出异常
 * @example
 * const user = await getUserById(123);
 */
async function getUserById(userId) {}

// 将日期格式化为 YYYY-MM-DD
const formattedDate = date.toISOString().slice(0, 10);

// TODO: 待实现的功能描述
// FIXME: 待修复的问题描述

// TODO: 用户登录失败超过5次应锁定账户
// FIXME: 密码加密逻辑性能低，需要优化

/**
 * 异步操作示例
 * @async
 * @param {Function} callback - 回调函数
 * @returns {Promise<void>}
 */
export async function doAsyncTask(callback) {
    try {
        const result = await someAsyncOperation();
        callback(null, result);
    } catch (err) {
        callback(err);
    }
}

/**
 * @file 模块名Controller.js
 * @description 控制器，处理接口请求逻辑
 * @author 作者名
 * @date YYYY-MM-DD
 * @version 1.0.0
 */
import { ModuleService } from '../service/moduleService.js';
​
export class ModuleController {
    constructor() {
        this.service = new ModuleService();
    }
​
    /**
     * 示例接口方法
     * @async
     * @param {Object} ctx - 请求上下文
     * @returns {Promise<void>}
     */
    async exampleMethod(ctx) {
        try {
            const data = await this.service.exampleService();
            ctx.body = { success: true, data };
        } catch (err) {
            ctx.status = 400;
            ctx.body = { success: false, message: err.message };
        }
    }
}

/**
 * @file moduleService.js
 * @description 服务层，处理业务逻辑
 * @author 作者名
 * @date YYYY-MM-DD
 * @version 1.0.0
 */
export class ModuleService {
    /**
     * 示例业务方法
     * @async
     * @returns {Promise<Object>} 返回结果
     */
    async exampleService() {
        // TODO: 实现业务逻辑
        return { message: '示例数据' };
    }
}

/**
 * @file moduleModel.js
 * @description 数据模型层，封装数据库操作
 */
export class ModuleModel {
    /**
     * 根据 ID 查询数据
     * @param {number} id - 数据ID
     * @returns {Promise<Object|null>} 数据对象或 null
     */
    static async findById(id) {
        // TODO: 数据库查询逻辑
        return null;
    }
​
    /**
     * 创建数据
     * @param {Object} data - 数据对象
     * @returns {Promise<Object>} 创建成功对象
     */
    static async create(data) {
        // TODO: 数据库写入逻辑
        return data;
    }
}

/**
 * @file utils.js
 * @description 工具函数集合
 */
​
/**
 * 格式化日期为 YYYY-MM-DD
 * @param {Date|string} date - 日期对象或字符串
 * @returns {string} 格式化后日期
 */
export function formatDate(date) {
    const d = date instanceof Date ? date : new Date(date);
    return d.toISOString().slice(0, 10);
}
​
/**
 * 获取当前时间戳（秒）
 * @returns {number} 当前时间戳
 */
export function nowTimestamp() {
    return Math.floor(Date.now() / 1000);
}