TypeScript命名规范详解变量、函数、类型与React组件的命名艺术【免费下载链接】typescript-style-guide⚙️ TypeScript Style Guide. A concise set of conventions and best practices for creating consistent, maintainable code.项目地址: https://gitcode.com/gh_mirrors/ty/typescript-style-guideTypeScript命名规范是编写高质量、可维护代码的关键要素之一。通过遵循一致的命名约定团队可以显著提高代码的可读性和可维护性。本文将深入探讨TypeScript命名规范的最佳实践帮助您掌握变量、函数、类型和React组件的命名艺术。为什么命名规范如此重要在大型项目中命名规范不仅仅是代码风格的问题它直接影响到代码可读性清晰的命名让其他开发者更容易理解代码意图团队协作效率一致的命名减少沟通成本和代码审查时间代码维护性规范的命名使代码重构和调试更加容易错误预防明确的命名可以减少因误解导致的bug变量命名规范从基础到高级基础变量命名规则变量命名是TypeScript代码中最常见的元素遵循以下原则普通变量使用小驼峰命名法camelCase// ✅ 推荐 const productList []; const userProfile {}; const filteredProducts []; // ❌ 避免 const product_list []; const UserProfile {}; const FILTEREDPRODUCTS [];布尔变量使用描述性前缀如is、has、can、should等// ✅ 推荐 const isActive true; const hasPermission false; const shouldRender true; const canEdit false; // ❌ 避免 const active true; const permission false; const render true;常量命名规范常量使用全大写字母和下划线分隔// ✅ 推荐 const MAX_RETRY_COUNT 3; const API_TIMEOUT 5000; const DEFAULT_USER_ROLE guest;对于对象和数组常量结合使用as const断言确保类型安全// ✅ 推荐 - 使用 const 断言 const USER_ROLES [admin, editor, moderator] as const; const APP_CONFIG { version: 1.0.0, debug: false, apiUrl: https://api.example.com, } as const;使用类型安全的常量当存在预定义类型时使用satisfies确保常量类型安全// 预定义类型 type UserRole admin | editor | moderator | viewer | guest; // ✅ 推荐 - 类型安全的常量 const DASHBOARD_ACCESS_ROLES [admin, editor, moderator] as const satisfies ReadonlyArrayUserRole;函数命名规范清晰表达意图函数命名基本原则函数命名应该清晰表达其功能使用动词开头// ✅ 推荐 function calculateTotalPrice() {} function getUserById() {} function formatCurrency() {} function validateEmail() {} // ❌ 避免 function totalPrice() {} // 缺少动词 function user() {} // 过于模糊 function currency() {} // 名词形式函数参数的最佳实践单一对象参数当函数需要多个参数时使用单一对象参数提高可读性和扩展性// ❌ 避免多个参数 transformUserInput(client, false, 60, 120, null, true, 2000); // ✅ 推荐使用选项对象 transformUserInput({ method: client, isValidated: false, minLines: 60, maxLines: 120, defaultInput: null, shouldLog: true, timeout: 2000, });避免过多可选参数如果函数变得过于复杂考虑将其拆分为多个小函数// ❌ 避免过多可选参数 function processData( data: Data, shouldValidate?: boolean, shouldLog?: boolean, timeout?: number, retryCount?: number, // ... 更多参数 ) {} // ✅ 推荐拆分为多个函数 function validateData(data: Data) {} function logData(data: Data) {} function processWithTimeout(data: Data, timeout: number) {}类型和接口命名规范类型别名命名类型别名使用帕斯卡命名法PascalCase// ✅ 推荐 type UserProfile { id: string; name: string; email: string; }; type OrderStatus pending | processing | completed | cancelled; // ❌ 避免 type user_profile {}; // 下划线 type Order_Status ; // 混合风格泛型类型参数命名泛型类型参数以大写字母T开头后跟描述性名称// ✅ 推荐 function createPairTFirst, TSecond extends string(first: TFirst, second: TSecond): [TFirst, TSecond] { return [first, second]; } // ❌ 避免单字母泛型 function createPairT, K(first: T, second: K): [T, K] { return [first, second]; }使用区分联合类型避免使用布尔标志而是使用区分联合类型// ❌ 避免布尔标志 const isPending true; const isProcessing false; const isConfirmed false; const isExpired false; // ✅ 推荐使用类型联合 type UserStatus pending | processing | confirmed | expired; const userStatus: UserStatus pending;React组件命名规范组件命名规则React组件使用帕斯卡命名法// ✅ 推荐 function ProductCard() {} const UserProfile () {}; class OrderList extends React.Component {} // ❌ 避免 function product_card() {} // 下划线 const userProfile () {}; // 小驼峰属性类型命名组件属性类型使用[ComponentName]Props格式// ✅ 推荐 type ProductCardProps { productId: string; productName: string; price: number; onSelect: (id: string) void; }; function ProductCard({ productId, productName, price, onSelect }: ProductCardProps) { // 组件实现 }回调属性命名约定事件处理程序属性使用on*前缀处理函数使用handle*前缀// ✅ 推荐 type ButtonProps { onClick: () void; onMouseEnter: () void; onFocus: () void; }; function Button({ onClick, onMouseEnter, onFocus }: ButtonProps) { const handleClick () { // 处理逻辑 onClick(); }; return button onClick{handleClick}点击我/button; }React Hooks命名规范自定义Hooks使用use前缀返回对象而不是数组// ✅ 推荐 - 返回对象 function useProducts() { const [products, setProducts] useStateProduct[]([]); const [loading, setLoading] useState(false); return { products, loading, setProducts }; } // ❌ 避免 - 返回数组 function useProducts() { const [products, setProducts] useStateProduct[]([]); const [loading, setLoading] useState(false); return [products, loading, setProducts]; }useState Hook对称命名使用对称的命名约定[value, setValue]// ✅ 推荐 const [userName, setUserName] useState(); const [isActive, setIsActive] useState(false); const [count, setCount] useState(0); // ❌ 避免 const [userName, setUser] useState(); // 不对称 const [color, updateColor] useState(); // 不一致的动词 const [isActive, setActive] useState(false); // 缺少is前缀缩写和首字母缩写处理首字母缩写处理将首字母缩写视为完整单词仅首字母大写// ✅ 推荐 const FaqList [qa-1, qa-2]; const generateUserUrl (params) {}; const parseXmlDocument (xml) {}; // ❌ 避免 const FAQList [qa-1, qa-2]; const generateUserURL (params) {}; const parseXMLDocument (xml) {};避免不必要的缩写除非广泛接受且必要否则避免使用缩写// ✅ 推荐 const getWindow (params) {}; const calculateMaximum (values) {}; const initializeApplication () {}; // ❌ 避免 const getWin (params) {}; const calcMax (values) {}; const initApp () {};注释与文档规范代码注释原则优先使用表达性代码而不是注释// ❌ 避免 - 解释性注释 // 转换为分钟 const m s * 60; // 每分钟平均用户数 const myAvg u / m; // ✅ 推荐 - 表达性代码 const SECONDS_IN_MINUTE 60; const minutes seconds * SECONDS_IN_MINUTE; const averageUsersPerMinute numberOfUsers / minutes;TSDoc注释为API、库和可重用代码使用TSDoc注释/** * 用户配置选项 */ type UserConfig { /** 用户唯一标识符 */ userId: string; /** * 用户角色 * - admin: 管理员权限 * - user: 普通用户权限 * - guest: 访客权限 */ role: admin | user | guest; /** 是否启用双因素认证 */ twoFactorEnabled?: boolean; };项目结构与导入规范按功能组织代码将代码按功能组织将相关代码尽可能靠近modules/ ├─ ProductsPage/ │ ├─ api/ │ │ └─ useGetProducts/ │ ├─ components/ │ │ └─ ProductItem/ │ ├─ utils/ │ │ └─ filterProductsByType/ │ └─ index.tsx导入路径规范使用相对导入处理同一功能内的文件使用绝对导入处理跨功能导入// ✅ 推荐 import { locationApi } from api/locationApi; // 绝对导入 import { foo } from ../../foo; // 相对导入 import { bar } from ../bar; // 相对导入 import { baz } from ./baz; // 相对导入 // ❌ 避免深层相对导入 import { bar, foo } from ../../../../../../distant-folder;命名规范的实际应用示例完整组件示例让我们看一个完整的React组件示例展示命名规范的实际应用// ProductItem.tsx type ProductItemProps { productId: string; productName: string; price: number; isOnSale: boolean; onAddToCart: (productId: string) void; onViewDetails: (productId: string) void; }; export const ProductItem ({ productId, productName, price, isOnSale, onAddToCart, onViewDetails, }: ProductItemProps) { const [isHovered, setIsHovered] useState(false); const handleMouseEnter () setIsHovered(true); const handleMouseLeave () setIsHovered(false); const handleAddToCartClick () onAddToCart(productId); const handleViewDetailsClick () onViewDetails(productId); return ( div onMouseEnter{handleMouseEnter} onMouseLeave{handleMouseLeave} h3{productName}/h3 p价格: ${price}/p {isOnSale span classNamesale-badge特价/span} button onClick{handleAddToCartClick}加入购物车/button button onClick{handleViewDetailsClick}查看详情/button /div ); };实用函数示例// utils/formatCurrency.ts type FormatCurrencyOptions { currency: USD | EUR | CNY; locale?: string; minimumFractionDigits?: number; maximumFractionDigits?: number; }; export const formatCurrency ( amount: number, options: FormatCurrencyOptions ): string { const { currency, locale zh-CN, minimumFractionDigits 2, maximumFractionDigits 2, } options; return new Intl.NumberFormat(locale, { style: currency, currency, minimumFractionDigits, maximumFractionDigits, }).format(amount); }; // 使用示例 const price formatCurrency(99.99, { currency: CNY });总结命名规范的核心原则通过遵循这些TypeScript命名规范您可以创建出一致且可读的代码库- 统一的命名约定让代码更易理解可维护的代码结构- 清晰的命名使重构和调试更加容易团队协作友好的环境- 减少沟通成本和代码审查时间类型安全的应用程序- 结合TypeScript的类型系统预防潜在错误记住良好的命名规范不仅仅是风格问题它是编写高质量、可维护TypeScript代码的基础。从今天开始实践这些规范您将看到代码质量的显著提升无论您是TypeScript新手还是经验丰富的开发者遵循这些命名规范都将帮助您编写出更清晰、更健壮的代码。开始应用这些最佳实践让您的TypeScript项目更加专业和高效【免费下载链接】typescript-style-guide⚙️ TypeScript Style Guide. A concise set of conventions and best practices for creating consistent, maintainable code.项目地址: https://gitcode.com/gh_mirrors/ty/typescript-style-guide创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考