Back to Details

typescript

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

TypeScript Code Style Guide

TypeScript代码风格指南

Types and Type Safety

类型与类型安全

Avoid explicit type annotations when TypeScript can infer
Avoid implicitly
```
any
```
; explicitly type when necessary
Use accurate types: prefer
```
Record<PropertyKey, unknown>
```
over
```
object
```
or
```
any
```
Prefer
```
interface
```
for object shapes (e.g., React props); use
```
type
```
for unions/intersections
Prefer
```
as const satisfies XyzInterface
```
over plain
```
as const
```
Prefer
```
@ts-expect-error
```
over
```
@ts-ignore
```
over
```
as any
```
Avoid meaningless null/undefined parameters; design strict function contracts

当TypeScript可以自动推断类型时，避免显式添加类型注解
避免隐式
```
any
```
类型；必要时显式声明类型
使用精确类型：优先选择
```
Record<PropertyKey, unknown>
```
而非
```
object
```
或
```
any
```
定义对象结构时优先使用
```
interface
```
（例如React props）；联合/交叉类型使用
```
type
```
优先选择
```
as const satisfies XyzInterface
```
而非单纯的
```
as const
```
优先使用
```
@ts-expect-error
```
，其次是
```
@ts-ignore
```
，避免使用
```
as any
```
避免无意义的null/undefined参数；设计严格的函数契约

Async Patterns

异步模式

Prefer
```
async
```
/
```
await
```
over callbacks or
```
.then()
```
chains
Prefer async APIs over sync ones (avoid
```
*Sync
```
)
Use promise-based variants:
```
import { readFile } from 'fs/promises'
```
Use
```
Promise.all
```
,
```
Promise.race
```
for concurrent operations where safe

优先使用
```
async
```
/
```
await
```
而非回调函数或
```
.then()
```
链式调用
优先选择异步API而非同步API（避免使用
```
*Sync
```
类方法）
使用基于Promise的变体：
```
import { readFile } from 'fs/promises'
```
在安全场景下，使用
```
Promise.all
```
、
```
Promise.race
```
处理并发操作

Code Structure

代码结构

Prefer object destructuring
Use consistent, descriptive naming; avoid obscure abbreviations
Replace magic numbers/strings with well-named constants
Defer formatting to tooling

优先使用对象解构
使用一致且具有描述性的命名；避免模糊的缩写
使用命名常量替代魔法数字/字符串
代码格式化交由工具处理

UI and Theming

UI与主题

Use
```
@lobehub/ui
```
, Ant Design components instead of raw HTML tags
Design for dark mode and mobile responsiveness
Use
```
antd-style
```
token system instead of hard-coded colors

使用
```
@lobehub/ui
```
、Ant Design组件而非原生HTML标签
适配暗黑模式与移动端响应式设计
使用
```
antd-style
```
令牌系统而非硬编码颜色

Performance

性能优化

Prefer
```
for…of
```
loops over index-based
```
for
```
loops
Reuse existing utils in
```
packages/utils
```
or installed npm packages
Query only required columns from database

优先选择
```
for…of
```
循环而非基于索引的
```
for
```
循环
复用
```
packages/utils
```
中已有的工具函数或已安装的npm包工具
仅从数据库查询所需的列

Time Consistency

时间一致性

Assign
```
Date.now()
```
to a constant once and reuse for consistency

先将
```
Date.now()
```
赋值给一个常量，然后复用该常量以保证一致性

Logging

日志规范

Never log user private information (API keys, etc.)
Don't use
```
import { log } from 'debug'
```
directly (logs to console)
Use
```
console.error
```
in catch blocks instead of debug package

切勿记录用户隐私信息（如API密钥等）
不要直接使用
```
import { log } from 'debug'
```
（会输出到控制台）
在catch块中使用
```
console.error
```
而非debug包