@constant 和 @readonly 的区别

在 JSDoc 中，@constant 和 @readonly 都用于表示“值不可变”，但它们的语义、使用场景和官方推荐度有重要区别。以下是详细对比：

---

✅ 1. @readonly

• 官方状态：✅ 推荐使用（JSDoc 官方当前标准）
• 语义：
  表示该成员初始化后不应被修改，强调“只读”行为。
• 典型使用场景：
  • 类的属性（最常见）：

    class Point {/*** X 坐标（只读）* @readonly*/x = 0;
    }
    

  • 模块级常量（较少见，因 const 已足够）：

    /** @readonly */
    const PI = 3.14159;
    

• 工具支持：
  • VS Code、TypeScript、TypeDoc、VitePress 等均良好支持。
  • 在文档中通常显示为 “Readonly” 标签。

📌 关键点：@readonly 更侧重于访问控制语义（外部不能改），而非声明方式。

---

⚠️ 2. @constant

• 官方状态：❌ 已弃用（deprecated）
• 语义：
  原意是表示“这是一个常量”，但与 JavaScript 的 const 关键字容易混淆。
• 问题：
  • 在早期 JSDoc 中使用，但现代规范已不推荐。
  • 官方文档明确指出：Use @readonly instead。
  • 不支持类型参数（如 @constant {number} 是无效语法）。
• 遗留用法示例（不推荐）：

  /** @constant */
  var MAX_SIZE = 100; // 用 var 声明的“逻辑常量”
  

🚫 结论：不要使用 @constant，它已被 @readonly 取代。

---

🔍 核心区别总结

特性	@readonly	@constant
官方状态	✅ 推荐	❌ 已弃用
语义重点	“只读”（不可修改）	“常量”（易与 const 混淆）
典型场景	类属性、配置项	旧代码遗留
是否支持类型	否（需配合 @type）	否（且 @constant {T} 无效）
现代工具支持	优秀	有限或忽略

---

🛠 正确使用示例

✅ 推荐：类属性（最常见）

class Config {/*** API 基础 URL（初始化后不可变）* @type {string}* @readonly*/baseUrl = 'https://api.example.com';
}

✅ 推荐：模块常量（通常无需标签）

// TypeScript：无需 JSDoc，类型和常量性自动推导
/** 默认超时时间（毫秒） */
export const DEFAULT_TIMEOUT = 5000;

❌ 避免：过时写法

/** @constant */        // ← 不要这样写
var VERSION = '1.0.0';

---

💡 为什么 @readonly 更合理？

JavaScript/TypeScript 中：

• const 保证变量绑定不可变（不能重新赋值），但对象内容仍可变：

  const obj = { x: 1 };
  obj.x = 2; // ✅ 允许！
  

• 而 @readonly 表达的是设计意图：这个值（无论是否 const）不应被外部修改，尤其适用于：
  • 类的公开属性
  • 配置对象字段
  • 库的导出常量（强调“请勿修改”）

---

✅ 最佳实践建议

1. 永远不要用 @constant → 改用 @readonly（如果确实需要标注）。
2. 对于 const 声明的简单值（如字符串、数字）：
   • 在 TypeScript 中：完全不需要 JSDoc 标签。
   • 在 JavaScript 中：只需描述性注释，除非类型不明显。
3. 仅在以下情况使用 @readonly：
   • 类的属性
   • 复杂对象的只读引用
   • 需要向用户强调“此值不可修改”的 API

---

📚 官方参考

From JSDoc official docs – @const:
"The @const tag is deprecated. Use @readonly instead."

---

总结一句话：

忘掉 @constant，用 @readonly 表示只读，而对 const 变量通常什么都不用写。