前端TypeScript配置规范书

前端TypeScript配置规范书一、TypeScript基础配置项规范1.compilerOptions核心基础配置1.1目标版本与模块系统target：必须明确指定ECMAScript目标版本，推荐设置为ES2020或更高版本。例如在Vue3+Vite项目中，设置为ES2020可充分利用现代JavaScript特性，同时保证主流浏览器的兼容性。禁止使用ES3、ES5等过低版本，避免限制语言特性的使用。module：根据项目构建工具和运行环境选择合适的模块系统。在Vite或Webpack5项目中，推荐使用ESNext以支持最新的ES模块语法；对于Node.js后端项目，可设置为CommonJS。禁止在浏览器端项目中使用Node16或NodeNext模块系统，避免出现兼容性问题。1.2严格模式与类型检查strict：强制开启严格模式，设置为true。开启后会同时启用noImplicitAny、strictNullChecks、strictFunctionTypes等一系列严格类型检查选项，从根源上避免类型相关的潜在错误。例如，在React项目中，开启严格模式后，组件的props必须明确指定类型，防止因隐式any类型导致的运行时错误。noImplicitAny：即使未开启strict模式，也必须单独将此选项设置为true。禁止变量或函数参数隐式推断为any类型，所有变量和参数都必须明确指定类型或通过类型推断确定具体类型。例如，在处理API响应数据时，必须为返回数据定义接口类型，而不是直接使用any类型接收。strictNullChecks：设置为true，严格检查null和undefined类型。在访问可能为null或undefined的变量时，必须进行显式的空值检查。例如，在使用可选链操作符?.之前，确保变量不为空，避免出现Cannotreadproperty'xxx'ofnull的错误。1.3模块解析与路径映射moduleResolution：推荐设置为NodeNext或Node16，以支持最新的Node.js模块解析策略。在使用ES模块和CommonJS模块混合的项目中，可确保模块解析的一致性。禁止使用Classic模块解析策略，因其已被废弃且存在解析逻辑不一致的问题。baseUrl与paths：在大型项目中，必须配置baseUrl和paths以简化模块导入路径。例如，将baseUrl设置为./src，然后通过paths配置将@/*映射到src/*，这样在导入模块时可以使用@/components/Button代替相对路径../../components/Button，提高代码的可读性和可维护性。配置示例如下：{"compilerOptions":{"baseUrl":"./src","paths":{"@/*":["*"]}}}2.include与exclude配置include：明确指定需要编译的文件路径，推荐设置为["src/**/*"]，表示编译src目录下的所有文件及子目录文件。禁止使用过于宽泛的路径，如["*"]，避免编译无关文件导致编译时间过长。exclude：指定需要排除编译的文件路径，默认会排除node_modules、bower_components、jspm_packages等目录。在实际项目中，可根据需要添加额外的排除路径，如["dist","build","**/*.test.ts"]，避免编译测试文件和构建输出目录中的文件。二、TypeScript与前端框架结合配置规范1.React项目配置1.1类型定义与JSX支持jsx：根据React版本和构建工具选择合适的JSX模式。在React17及以上版本中，推荐设置为react-jsx，以支持新的JSX转换，无需在文件顶部导入React。对于旧版本React项目，可设置为react。types：必须包含react、react-dom等相关类型定义，同时根据项目使用的UI库添加对应的类型包，如@types/antd、@types/material-ui等。例如，在使用AntDesign的React项目中，需确保types配置中包含antd的类型定义：{"compilerOptions":{"types":["react","react-dom","antd"]}}1.2自定义类型声明在项目根目录创建src/types目录，用于存放自定义类型声明文件。例如，创建src/types/index.d.ts文件，定义全局类型或扩展现有类型：declareglobal{interfaceWindow{__REDUX_DEVTOOLS_EXTENSION_COMPOSE__:typeofcompose;}}export{};对于第三方库缺失类型定义的情况，可在src/types目录下创建对应的.d.ts文件进行类型声明。例如，为一个没有类型定义的工具库utils-lib创建类型声明文件src/types/utils-lib.d.ts：declaremodule'utils-lib'{exportfunctionformatDate(date:Date):string;exportfunctionformatNumber(num:number):string;}2.Vue项目配置2.1Vite+Vue3项目配置vueCompilerOptions：在tsconfig.json中添加vueCompilerOptions配置项，以支持Vue3的单文件组件类型检查。例如：{"vueCompilerOptions":{"target":3,"strictTemplates":true,"experimentalRuntimeMode":"module"}}其中，strictTemplates设置为true，开启模板的严格类型检查，确保模板中的变量和表达式类型正确。types：必须包含vite/client和vue类型定义，同时根据项目使用的Vue插件添加对应的类型包，如@vue/runtime-core、@vue/test-utils等。2.2Vue2项目配置对于Vue2项目，需使用@vue/cli创建并配置TypeScript。在tsconfig.json中，target推荐设置为ES2018，module设置为ESNext。同时，需安装@vue/composition-api类型定义包，并在types配置中添加@vue/composition-api。在Vue2单文件组件中，必须使用lang="ts"指定脚本语言为TypeScript，并通过defineComponent函数定义组件，以支持类型推断。例如：import{defineComponent}from'vue';exportdefaultdefineComponent({name:'HelloWorld',props:{msg:{type:String,required:true}},setup(props){//此处props会自动推断类型return{props};}});三、TypeScript与构建工具结合配置规范1.Webpack项目配置1.1ts-loader配置在Webpack配置文件中，使用ts-loader处理TypeScript文件。必须指定configFile选项，指向项目根目录下的tsconfig.json文件，确保TypeScript编译使用项目的配置规范。示例配置如下：module.exports={module:{rules:[{test:/\.tsx?$/,use:[{loader:'ts-loader',options:{configFile:'tsconfig.json'}}],exclude:/node_modules/}]}};对于大型项目，可启用transpileOnly选项提高编译速度，但必须配合fork-ts-checker-webpack-plugin插件进行类型检查，避免因只编译不检查类型导致错误。1.2fork-ts-checker-webpack-plugin配置安装并配置fork-ts-checker-webpack-plugin插件，将类型检查与编译过程分离，提高Webpack构建速度。在Webpack配置文件中添加如下配置：constForkTsCheckerWebpackPlugin=require('fork-ts-checker-webpack-plugin');module.exports={plugins:[newForkTsCheckerWebpackPlugin({typescript:{configFile:'tsconfig.json'}})]};插件会在单独的进程中进行类型检查，不会阻塞Webpack的编译过程，同时将类型检查错误输出到控制台。2.Vite项目配置2.1内置TypeScript支持Vite内置了对TypeScript的支持，无需额外配置ts-loader或babel-loader。只需在项目根目录下创建tsconfig.json文件，Vite会自动读取并使用其中的配置。在vite.config.ts中，可通过optimizeDeps选项对依赖进行预构建，提高开发时的启动速度。例如，对一些大型第三方库进行预构建：import{defineConfig}from'vite';exportdefaultdefineConfig({optimizeDeps:{include:['lodash-es','axios']}});2.2类型检查与ESLint集成Vite默认不会在开发过程中进行TypeScript类型检查，需安装vite-plugin-checker插件并配置，以在开发时实时进行类型检查和ESLint检查。示例配置如下：import{defineConfig}from'vite';importcheckerfrom'vite-plugin-checker';exportdefaultdefineConfig({plugins:[checker({typescript:true,eslint:{lintCommand:'eslint"./src/**/*.{ts,tsx}"'}})]});配置后，在开发过程中，Vite会在控制台实时显示类型检查和ESLint检查的错误信息。四、TypeScript代码风格与规范1.变量与函数命名规范变量命名：采用小驼峰命名法，即首字母小写，后续单词首字母大写。例如：userName、totalCount。禁止使用下划线或连字符命名变量，如user_name或user-name。对于常量，全部使用大写字母，单词之间用下划线分隔，例如：MAX_RETRY_COUNT、API_BASE_URL。函数命名：同样采用小驼峰命名法，动词开头，清晰表达函数的功能。例如：getUserInfo、formatDateTime。构造函数或类名采用大驼峰命名法，首字母大写，例如：UserService、OrderManager。接口与类型别名命名：采用大驼峰命名法，接口名以I开头（可选，但团队需统一规范），类型别名以T开头（可选）。例如：IUser、TOrderList。禁止使用小驼峰或下划线命名接口和类型别名。2.类型定义与使用规范接口定义：在定义对象类型时，优先使用接口（interface）而不是类型别名（type）。接口支持声明合并，便于后续扩展。例如，定义用户信息接口：interfaceIUser{id:number;name:string;email:string;}//后续可扩展接口interfaceIUser{age?:number;}类型别名使用场景：当定义联合类型、交叉类型或元组类型时，使用类型别名。例如：typeStatus='success'|'error'|'pending';typeTUserWithAddress=IUser&{address:string};typeTCoordinate=[number,number];避免重复类型定义：对于项目中多次使用的类型，统一定义在src/types目录下的类型声明文件中，避免在多个文件中重复定义相同的类型。例如，将API响应数据的通用类型定义在src/types/api.d.ts中：interfaceIApiResponse<T>{code:number;message:string;data:T;}3.函数与类的类型规范函数参数与返回值类型：所有函数的参数和返回值都必须明确指定类型。对于可选参数，使用?标记，默认参数直接在参数中指定默认值。例如：functionfetchUser(id:number,includeAddress?:boolean):Promise<IUser>{//函数实现}functioncalculateTotal(prices:number[],discount:number=0):number{returnprices.reduce((total,price)=>total+price*(1-discount),0);}类的成员类型：类的属性和方法必须明确指定类型。对于私有成员，使用private修饰符，受保护成员使用protected修饰符。例如：classUserService{privateapiBaseUrl:string;constructor(apiBaseUrl:string){this.apiBaseUrl=apiBaseUrl;}publicasyncgetUser(id:number):Promise<IUser>{constresponse=awaitfetch(`${this.apiBaseUrl}/users/${id}`);returnresponse.json();}}五、TypeScript项目目录结构规范1.基础目录结构project-root/├──src/│├──assets/#静态资源文件，如图片、样式等│├──components/#公共组件│├──hooks/#自定义ReactHooks或Vue组合式函数│├──layouts/#页面布局组件│├──pages/#页面组件│├──services/#API请求服务│├──store/#状态管理（如Redux、Pinia）│├──types/#全局类型定义│├──utils/#工具函数│├──App.tsx#根组件（React项目）│├──main.ts#项目入口文件│└──router/#路由配置├──tests/#测试文件├──.eslintrc.js#ESLint配置├──.prettierrc.js#Prettier配置├──tsconfig.json#TypeScript配置└──package.json#项目依赖配置2.目录职责与文件命名src/components目录：存放可复用的公共组件，每个组件对应一个子目录，目录名采用大驼峰命名法，组件文件名为index.tsx（React）或index.vue（Vue）。例如：src/components/├──Button/│├──index.tsx│├──Button.module.css│└──Button.test.tsx└──Input/├──index.tsx├──Input.module.css└──Input.test.tsxsrc/services目录：按业务模块划分子目录，每个子目录下的文件对应具体的API请求服务。例如：src/services/├──user/│├──index.ts│└──types.ts└──order/├──index.ts└──types.ts其中，index.ts文件存放API请求函数，types.ts文件存放该模块相关的类型定义。src/utils目录：按功能划分工具函数，每个工具函数对应一个文件，文件名采用小驼峰命名法。例如：date-utils.ts、string-utils.ts。禁止将所有工具函数都放在一个utils.ts文件中，提高代码的可维护性。六、TypeScript与ESLint、Prettier集成规范1.ESLint配置安装依赖：必须安装@typescript-eslint/eslint-plugin和@typescript-eslint/parser作为ESLint的TypeScript插件和解析器。同时，根据项目使用的前端框架安装对应的ESLint插件，如eslint-plugin-react、eslint-plugin-vue。配置文件：在.eslintrc.js中配置解析器和插件，示例如下（React项目）：module.exports={parser:'@typescript-eslint/parser',plugins:['@typescript-eslint','react'],extends:['eslint:recommended','plugin:@typescript-eslint/recommended','plugin:react/recommended','plugin:react-hooks/recommended'],rules:{'@typescript-eslint/no-unused-vars':['error',{argsIgnorePattern:'^_'}],'@typescript-eslint/explicit-function-return-type':'off','react/react-in-jsx-scope':'off'}};其中，@typescript-eslint/no-unused-vars规则设置为error级别，同时忽略以_开头的未使用变量，便于处理函数参数中未使用的情况。2.Prettier配置安装依赖：安装prettier以及eslint-config-prettier和eslint-plugin-prettier，以实现ESLin