codebelt-code-style

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

CodeBelt Code Style Guide

CodeBelt代码风格指南

Opinionated TypeScript and React code style for consistency, maintainability, and scalability. Apply these rules when writing new code, reviewing existing code, or refactoring.

这是一套具有主见的TypeScript与React代码风格规范，旨在保障代码的一致性、可维护性与可扩展性。编写新代码、评审现有代码或重构时请遵循这些规则。

Quick Reference

快速参考

File Placement

文件存放位置

Code Type	Location
React component	`components/pages/` , `components/shared/` , or `components/ui/`
API logic	`services/{provider}/{service}/`
Reusable function	`utils/{utilName}/`
React hook	`hooks/use{HookName}/`
Third-party config	`libs/{libraryName}/`

代码类型	存放路径
React组件	`components/pages/` 、 `components/shared/` 或 `components/ui/`
API逻辑	`services/{provider}/{service}/`
可复用函数	`utils/{utilName}/`
React Hook	`hooks/use{HookName}/`
第三方配置	`libs/{libraryName}/`

File Extensions

文件扩展名

Extension	Purpose
`.ts{x}`	Main code ( `.tsx` only when file contains JSX)
`.test.ts`	Tests
`.types.ts`	TypeScript types
`.utils.ts{x}`	Helper functions
`.utils.test.ts`	Tests for utility functions
`.schemas.ts`	Zod validation schemas
`.schemas.test.ts`	Tests for schemas
`.constants.ts{x}`	Static objects and constants

扩展名	用途
`.ts{x}`	主代码文件（仅当文件包含JSX时使用 `.tsx` ）
`.test.ts`	测试文件
`.types.ts`	TypeScript类型定义文件
`.utils.ts{x}`	辅助函数文件
`.utils.test.ts`	辅助函数测试文件
`.schemas.ts`	Zod校验schema文件
`.schemas.test.ts`	Schema测试文件
`.constants.ts{x}`	静态对象与常量文件

Naming Conventions

命名规范

Context	Convention	Example
Component folders	camelCase	`userCard/`
Component files	PascalCase	`UserCard.tsx`
Everything else	camelCase	`httpClient.ts`
Variables/params	Descriptive (no single chars)	`event` not `e`
Constants	camelCase	`maxRetries` not `MAX_RETRIES`

场景	规范	示例
组件文件夹	小驼峰式（camelCase）	`userCard/`
组件文件	大驼峰式（PascalCase）	`UserCard.tsx`
其他所有文件	小驼峰式（camelCase）	`httpClient.ts`
变量/参数	描述性命名（禁止单字符）	`event` 而非 `e`
常量	小驼峰式（camelCase）	`maxRetries` 而非 `MAX_RETRIES`

Exports

导出规则

All files use named exports only:

typescript

export function Component() {}

No default exports. No barrel files in application code.

所有文件仅使用命名导出：

typescript

export function Component() {}

禁止使用默认导出。应用代码中禁止使用桶文件（barrel files）。

Workflows

工作流程

Creating a New Component

创建新组件

Create folder:

components/{pages|shared|ui}/{componentName}/

Create component file:
```
{ComponentName}.tsx
```
with Props type and JSX only
Extract types to
```
{ComponentName}.types.ts
```
(if needed beyond Props)
Extract constants to
```
{ComponentName}.constants.ts
```
(if any)
Extract helpers to
```
{ComponentName}.utils.ts
```
(if any)
Verify: one component per file, Props not exported, named export

创建文件夹：

components/{pages|shared|ui}/{componentName}/

创建组件文件：
```
{ComponentName}.tsx
```
，仅包含Props类型与JSX代码
若Props之外还有其他类型定义，将其提取至
```
{ComponentName}.types.ts
```
若有静态常量，将其提取至
```
{ComponentName}.constants.ts
```
若有辅助函数，将其提取至
```
{ComponentName}.utils.ts
```
检查：每个文件对应一个组件，Props不对外导出，使用命名导出

Creating a New Service

创建新服务

Create folder:
```
services/{provider}/{serviceName}/
```
Create main file:
```
{serviceName}.ts
```
with fetch functions and query hooks
Create schema file:
```
{serviceName}.schemas.ts
```
with Zod schemas
Create constants file:
```
{serviceName}.constants.ts
```
with query keys
Verify: schema and type share same name, comment with HTTP method and path

创建文件夹：
```
services/{provider}/{serviceName}/
```
创建主文件：
```
{serviceName}.ts
```
，包含请求函数与查询Hook
创建schema文件：
```
{serviceName}.schemas.ts
```
，包含Zod校验schema
创建常量文件：
```
{serviceName}.constants.ts
```
，包含查询键
检查：schema与类型使用相同名称，添加包含HTTP方法与路径的注释

Creating a New Hook

创建新Hook

Create folder:
```
hooks/use{HookName}/
```
Create hook file:
```
use{HookName}.ts
```
Create test file:
```
use{HookName}.test.ts
```

创建文件夹：
```
hooks/use{HookName}/
```
创建Hook文件：
```
use{HookName}.ts
```
创建测试文件：
```
use{HookName}.test.ts
```

Creating a New Utility

创建新工具函数

Create folder:
```
utils/{utilName}/
```
Create utility file:
```
{utilName}.ts
```
(no
```
.utils.ts
```
suffix inside
```
utils/
```
)
Create test file:
```
{utilName}.test.ts
```

创建文件夹：
```
utils/{utilName}/
```
创建工具函数文件：
```
{utilName}.ts
```
（
```
utils/
```
目录下的文件无需添加
```
.utils.ts
```
后缀）
创建测试文件：
```
{utilName}.test.ts
```

Detailed References

详细参考

Component patterns and hierarchy: See COMPONENTS.md
Service and schema patterns: See SERVICES.md
Testing patterns: See TESTING.md
Common mistakes to avoid: See MISTAKES.md

组件模式与层级结构：参见 COMPONENTS.md
服务与Schema模式：参见 SERVICES.md
测试模式：参见 TESTING.md
需避免的常见错误：参见 MISTAKES.md