如何通过ESLint和TypeScript禁用JSON全局变量并强制使用封装函数

一、ESLint 层面拦截原生JSON方法 #

之前设置globals: { JSON: "off" }无效，是因为原生JSON属于环境内置对象，ESLint默认不会主动拦截。可以通过以下规则实现限制：

1. 精准禁用JSON.stringify/JSON.parse #

在.eslintrc.js中配置no-restricted-properties规则，直接禁止调用这两个方法：

module.exports = {
  rules: {
    'no-restricted-properties': [
      'error',
      {
        object: 'JSON',
        property: 'stringify',
        message: '请使用项目封装的stringify函数替代原生JSON.stringify'
      },
      {
        object: 'JSON',
        property: 'parse',
        message: '请使用项目封装的parseJSON函数替代原生JSON.parse'
      }
    ]
  }
};

代码中直接调用原生方法时，ESLint会抛出错误并给出明确提示。

2. 全局禁用整个JSON对象（可选） #

如果要彻底禁止使用JSON对象，可结合no-restricted-globals规则：

module.exports = {
  rules: {
    'no-restricted-globals': [
      'error',
      {
        name: 'JSON',
        message: '禁止直接使用原生JSON对象，请使用封装后的处理函数'
      }
    ]
  }
};

若封装函数内部需要调用原生JSON，可在封装文件中添加注释忽略规则：

// eslint-disable-next-line no-restricted-globals, no-restricted-properties
export const stringify = (data: unknown) => {
  try {
    return JSON.stringify(data);
  } catch (err) {
    // 自定义错误处理与日志逻辑
    console.error('JSON序列化失败:', err);
    throw new Error('序列化数据出错');
  }
};

二、TypeScript 编译阶段限制 #

之前声明global.JSON = null无效，因为TS会优先读取内置的JSON类型定义。可以通过类型覆盖+TS ESLint规则实现拦截：

1. 覆盖全局JSON类型 #

在项目根目录的global.d.ts中重新定义JSON接口，将stringify和parse标记为never类型：

declare global {
  interface JSON {
    stringify: never;
    parse: never;
  }
}

export {};

确保该文件被tsconfig.json的include字段包含：

{
  "include": ["src/**/*", "global.d.ts"]
}

此时开发者调用原生方法时，TS会直接抛出编译错误：“类型为never的属性不可调用”。

2. 配合TS专属ESLint规则 #

使用@typescript-eslint/no-restricted-properties规则，比原生ESLint规则更适配TS语法：

module.exports = {
  parser: '@typescript-eslint/parser',
  plugins: ['@typescript-eslint'],
  rules: {
    '@typescript-eslint/no-restricted-properties': [
      'error',
      {
        object: 'JSON',
        property: 'stringify',
        message: '请使用项目封装的stringify函数'
      },
      {
        object: 'JSON',
        property: 'parse',
        message: '请使用项目封装的parseJSON函数'
      }
    ]
  }
};

三、落地保障建议 #

• 将封装的stringify/parseJSON函数统一放在项目工具库（如src/utils/json.ts），并通过文档明确要求团队使用。
• 在CI/CD流程中加入ESLint检查和TS编译步骤，拦截违规代码合并到主分支。

内容的提问来源于stack exchange，提问作者Noah May