编码标准配置

// 变量：camelCase，名词性
const userName = 'john';
const itemCount = 10;
const isActive = true;
 
// 函数：camelCase，动词开头
function getUserById(id: string) { }
function calculateTotal(items: Item[]) { }
function validateEmail(email: string) { }
 
// 常量：SCREAMING_SNAKE_CASE
const MAX_RETRY_COUNT = 3;
const API_BASE_URL = 'https://api.example.com';

# 变量：snake_case，名词性
user_name = 'john'
item_count = 10
is_active = True
 
# 函数：snake_case，动词开头
def get_user_by_id(user_id: str) -> User:
    pass
 
def calculate_total(items: list[Item]) -> float:
    pass
 
def validate_email(email: str) -> bool:
    pass
 
# 常量：SCREAMING_SNAKE_CASE
MAX_RETRY_COUNT = 3
API_BASE_URL = 'https://api.example.com'

// 变量：camelCase，名词性
$userName = 'john';
$itemCount = 10;
$isActive = true;
 
// 方法：camelCase，动词开头
public function getUserById(string $id): User { }
public function calculateTotal(array $items): float { }
public function validateEmail(string $email): bool { }
 
// 常量：SCREAMING_SNAKE_CASE
const MAX_RETRY_COUNT = 3;
const API_BASE_URL = 'https://api.example.com';

// 类：PascalCase，名词
class UserService { }
class OrderRepository { }
 
// 接口：PascalCase，可选 I 前缀（按团队约定）
interface User { }
interface IUserService { }  // 可选风格
 
// 类型：PascalCase
type UserRole = 'admin' | 'user' | 'guest';
type ApiResponse<T> = { data: T; error?: string };

# 类：PascalCase，名词
class UserService:
    pass
 
class OrderRepository:
    pass
 
# 协议/抽象类：PascalCase
from typing import Protocol
 
class UserRepositoryProtocol(Protocol):
    def get_by_id(self, user_id: str) -> User: ...
 
# 类型别名：PascalCase
UserRole = Literal['admin', 'user', 'guest']

// 类：PascalCase，名词
class UserService { }
class OrderRepository { }
 
// 接口：PascalCase，可选 Interface 后缀
interface UserRepositoryInterface { }
interface Authenticatable { }
 
// Trait：PascalCase
trait HasTimestamps { }
trait Notifiable { }

## 命名规范（TypeScript）
 
### 文件命名
- 普通文件：kebab-case.ts（如 user-service.ts）
- React 组件：PascalCase.tsx（如 UserProfile.tsx）
- 测试文件：*.test.ts 或 *.spec.ts
 
### 标识符命名
- 变量/函数：camelCase（如 getUserById）
- 类/接口/类型：PascalCase（如 UserService）
- 常量：SCREAMING_SNAKE_CASE（如 MAX_RETRY）
- 布尔值：is/has/can/should 前缀（如 isActive）
 
### 命名原则
- 变量名用名词，函数名用动词
- 名称要有意义，避免 a, b, x, temp
- 不使用缩写，除非是广泛认可的（如 id, url）

## 命名规范（Python）
 
### 文件命名
- 模块文件：snake_case.py（如 user_service.py）
- 测试文件：test_*.py 或 *_test.py
 
### 标识符命名
- 变量/函数：snake_case（如 get_user_by_id）
- 类：PascalCase（如 UserService）
- 常量：SCREAMING_SNAKE_CASE（如 MAX_RETRY）
- 私有成员：_leading_underscore（如 _internal_method）
- 布尔值：is/has/can/should 前缀（如 is_active）
 
### 命名原则
- 遵循 PEP 8 规范
- 变量名用名词，函数名用动词
- 避免单字符命名（循环变量除外）

## 命名规范（PHP）
 
### 文件命名
- 类文件：PascalCase.php（如 UserService.php）
- 普通文件：snake_case.php（如 helpers.php）
- 测试文件：*Test.php（如 UserServiceTest.php）
 
### 标识符命名
- 变量：camelCase（如 $userName）
- 方法：camelCase（如 getUserById）
- 类/接口/Trait：PascalCase（如 UserService）
- 常量：SCREAMING_SNAKE_CASE（如 MAX_RETRY）
- 布尔值：is/has/can/should 前缀（如 $isActive）
 
### 命名原则
- 遵循 PSR-12 规范
- 类名与文件名一致
- 命名空间与目录结构一致

// ❌ 差：一个函数做多件事
function processUser(user: User) {
  // 验证用户
  if (!user.email) throw new Error('Invalid email');
  // 保存到数据库
  db.save(user);
  // 发送欢迎邮件
  sendEmail(user.email, 'Welcome!');
  // 记录日志
  logger.info('User created');
}
 
// ✅ 好：每个函数只做一件事
function validateUser(user: User): void {
  if (!user.email) throw new Error('Invalid email');
}
 
function saveUser(user: User): void {
  db.save(user);
}
 
function sendWelcomeEmail(email: string): void {
  sendEmail(email, 'Welcome!');
}
 
function createUser(user: User): void {
  validateUser(user);
  saveUser(user);
  sendWelcomeEmail(user.email);
  logger.info('User created');
}

# ❌ 差：一个函数做多件事
def process_user(user: User) -> None:
    # 验证用户
    if not user.email:
        raise ValueError('Invalid email')
    # 保存到数据库
    db.save(user)
    # 发送欢迎邮件
    send_email(user.email, 'Welcome!')
    # 记录日志
    logger.info('User created')
 
# ✅ 好：每个函数只做一件事
def validate_user(user: User) -> None:
    if not user.email:
        raise ValueError('Invalid email')
 
def save_user(user: User) -> None:
    db.save(user)
 
def send_welcome_email(email: str) -> None:
    send_email(email, 'Welcome!')
 
def create_user(user: User) -> None:
    validate_user(user)
    save_user(user)
    send_welcome_email(user.email)
    logger.info('User created')

// ❌ 差：一个函数做多件事
public function processUser(User $user): void {
    // 验证用户
    if (!$user->email) throw new Exception('Invalid email');
    // 保存到数据库
    $this->db->save($user);
    // 发送欢迎邮件
    $this->sendEmail($user->email, 'Welcome!');
    // 记录日志
    $this->logger->info('User created');
}
 
// ✅ 好：每个函数只做一件事
public function validateUser(User $user): void {
    if (!$user->email) throw new InvalidArgumentException('Invalid email');
}
 
public function saveUser(User $user): void {
    $this->db->save($user);
}
 
public function sendWelcomeEmail(string $email): void {
    $this->sendEmail($email, 'Welcome!');
}
 
public function createUser(User $user): void {
    $this->validateUser($user);
    $this->saveUser($user);
    $this->sendWelcomeEmail($user->email);
    $this->logger->info('User created');
}

// ❌ 差：参数过多
function createUser(
  name: string,
  email: string,
  age: number,
  address: string,
  phone: string,
  role: string
) { }
 
// ✅ 好：使用对象参数
interface CreateUserParams {
  name: string;
  email: string;
  age: number;
  address: string;
  phone: string;
  role: string;
}
 
function createUser(params: CreateUserParams) { }

# ❌ 差：参数过多
def create_user(
    name: str,
    email: str,
    age: int,
    address: str,
    phone: str,
    role: str
) -> User:
    pass
 
# ✅ 好：使用 dataclass
@dataclass
class CreateUserParams:
    name: str
    email: str
    age: int
    address: str
    phone: str
    role: str
 
def create_user(params: CreateUserParams) -> User:
    pass

// ❌ 差：参数过多
public function createUser(
    string $name,
    string $email,
    int $age,
    string $address,
    string $phone,
    string $role
): User { }
 
// ✅ 好：使用 DTO
class CreateUserDto {
    public function __construct(
        public string $name,
        public string $email,
        public int $age,
        public string $address,
        public string $phone,
        public string $role,
    ) {}
}
 
public function createUser(CreateUserDto $dto): User { }

// ✅ 明确返回类型
function getUserById(id: string): User | null {
  const user = db.find(id);
  return user ?? null;
}
 
// ✅ 使用 Result 模式处理错误
type Result<T, E> = { ok: true; value: T } | { ok: false; error: E };
 
function parseJson(str: string): Result<unknown, Error> {
  try {
    return { ok: true, value: JSON.parse(str) };
  } catch (e) {
    return { ok: false, error: e as Error };
  }
}

from typing import Optional
 
# ✅ 明确返回类型
def get_user_by_id(user_id: str) -> Optional[User]:
    user = db.find(user_id)
    return user if user else None
 
# ✅ 使用 Result 模式（或返回元组）
from dataclasses import dataclass
from typing import Generic, TypeVar, Union
 
T = TypeVar('T')
E = TypeVar('E')
 
@dataclass
class Ok(Generic[T]):
    value: T
 
@dataclass
class Err(Generic[E]):
    error: E
 
Result = Union[Ok[T], Err[E]]
 
def parse_json(s: str) -> Result[dict, str]:
    try:
        return Ok(json.loads(s))
    except json.JSONDecodeError as e:
        return Err(str(e))

// ✅ 明确返回类型（PHP 8+）
public function getUserById(string $id): ?User {
    $user = $this->db->find($id);
    return $user ?? null;
}
 
// ✅ 使用 Result 模式
class Result {
    private function __construct(
        public readonly bool $ok,
        public readonly mixed $value = null,
        public readonly ?string $error = null,
    ) {}
 
    public static function ok(mixed $value): self {
        return new self(true, $value);
    }
 
    public static function err(string $error): self {
        return new self(false, error: $error);
    }
}
 
public function parseJson(string $str): Result {
    try {
        return Result::ok(json_decode($str, true, flags: JSON_THROW_ON_ERROR));
    } catch (JsonException $e) {
        return Result::err($e->getMessage());
    }
}

// ✅ 可选链
const userName = user?.profile?.name;
 
// ✅ 空值合并
const displayName = userName ?? 'Anonymous';
 
// ✅ 提前返回，避免深层嵌套
function getDisplayName(user: User | null): string {
  if (!user) return 'Anonymous';
  if (!user.profile) return user.email;
  return user.profile.name ?? user.email;
}

from typing import Optional
 
# ✅ 使用 Optional 类型注解
def get_user_name(user: Optional[User]) -> str:
    if user is None:
        return 'Anonymous'
    return user.name or 'Anonymous'
 
# ✅ 使用 or 提供默认值
display_name = user_name or 'Anonymous'
 
# ✅ getattr 带默认值
name = getattr(user, 'name', 'Anonymous')

// ✅ 空值合并运算符
$userName = $user?->profile?->name;
 
// ✅ 空值合并赋值
$displayName = $userName ?? 'Anonymous';
 
// ✅ 提前返回
public function getDisplayName(?User $user): string {
    if ($user === null) return 'Anonymous';
    if ($user->profile === null) return $user->email;
    return $user->profile->name ?? $user->email;
}

## 错误处理规范（TypeScript）
 
### 类型安全
- 绝不使用 any，catch 块使用 unknown
- 使用类型守卫验证错误类型
- 自定义错误类继承 Error
 
### 错误处理原则
- 绝不吞掉异常（空 catch 块）
- 捕获的异常必须记录或重新抛出
- 错误信息必须包含上下文
 
### 空值处理
- 使用可选链 (?.) 访问可能为空的属性
- 使用空值合并 (??) 提供默认值
- 显式检查 null/undefined，不依赖隐式转换

## 错误处理规范（Python）
 
### 异常处理
- 绝不使用 bare except
- 捕获具体的异常类型
- 使用 raise from 保留异常链
 
### 自定义异常
- 继承合适的内置异常类
- 包含有意义的错误信息和上下文
- 遵循异常类命名规范（*Error 或 *Exception）
 
### 空值处理
- 使用 Optional 类型注解
- 使用 is None 而非 == None
- 使用 or 运算符提供默认值

## 错误处理规范（PHP）
 
### 异常处理
- 绝不使用 @ 错误抑制符
- 捕获具体的异常类型
- 使用 previous 参数保留异常链
 
### 自定义异常
- 建立项目异常层次结构
- 异常类包含错误码和上下文
- 遵循 PSR 规范
 
### 空值处理
- 使用 ?-> 空值安全运算符（PHP 8+）
- 使用 ?? 空值合并运算符
- 参数和返回值使用 nullable 类型

// 1. 外部库（node_modules）
import express from 'express';
import { z } from 'zod';
 
// 2. 内部模块（绝对路径）
import { UserService } from '@/services/user';
import { logger } from '@/utils/logger';
 
// 3. 相对路径
import { validateUser } from './validators';
import type { User } from './types';

# 1. 标准库
import os
import sys
from datetime import datetime
 
# 2. 第三方库
import requests
from pydantic import BaseModel
 
# 3. 本地模块
from app.services.user import UserService
from app.utils.logger import logger
 
from .validators import validate_user
from .types import User

<?php
 
// 严格类型声明
declare(strict_types=1);
 
namespace App\Services;
 
// use 语句按字母排序
use App\Exceptions\ApiException;
use App\Models\User;
use App\Repositories\UserRepository;
use Psr\Log\LoggerInterface;
 
class UserService
{
    // ...
}

/**
 * 根据用户 ID 获取用户信息
 *
 * @param id - 用户唯一标识符
 * @returns 用户对象，如果不存在返回 null
 * @throws {ApiError} 当数据库连接失败时
 *
 * @example
 * ```ts
 * const user = await getUserById('123');
 * if (user) {
 *   console.log(user.name);
 * }
 * ```
 */
async function getUserById(id: string): Promise<User | null> {
  // ...
}

def get_user_by_id(user_id: str) -> Optional[User]:
    """根据用户 ID 获取用户信息
 
    Args:
        user_id: 用户唯一标识符
 
    Returns:
        用户对象，如果不存在返回 None
 
    Raises:
        ApiError: 当数据库连接失败时
 
    Example:
        >>> user = get_user_by_id('123')
        >>> if user:
        ...     print(user.name)
    """
    # ...

/**
 * 根据用户 ID 获取用户信息
 *
 * @param string $id 用户唯一标识符
 * @return User|null 用户对象，如果不存在返回 null
 * @throws ApiException 当数据库连接失败时
 *
 * @example
 * $user = $this->getUserById('123');
 * if ($user !== null) {
 *     echo $user->getName();
 * }
 */
public function getUserById(string $id): ?User
{
    // ...
}