Encoding-Specification/README.md

编码规范

目标：统一团队的编码风格、工程结构、质量门槛与评审流程，降低维护成本并提升可读性与安全性。

---

总体原则（适用于所有语言）

• 一致优先：团队内以本规范为准；历史代码可在“动则改之”的前提下逐步迁移。
• 自动化为先：全部项目必须配置“格式化+ 单元测试”，并在 CI 强制执行。
• 最小接口：公开 API 保持最小化，隐藏实现细节；遵循“只暴露需要被依赖的东西”。
• 可读性：命名清晰、函数短小（通常 ≤ 40 行），模块单一职责。
• 防御式编程：显式边界检查、错误处理、输入校验、超时与重试策略。
• 不可变优先：能用不可变结构/值对象则优先使用；避免可变全局状态。
• 安全默认：启用严格编译/类型校验、依赖锁定与安全基线（见各语言安全节）。
• 文档与注释：公开类型/函数必须有 API 文档；复杂逻辑用块注释解释“为什么”。
• 提交规范：见 Git 管理规范。
• 代码评审：至少 1 名 Reviewer；禁止自我合并；高风险改动需 2 人评审与灰度。

---

Java 规范

版本与工具

• 运行时：Java 24+。
• 构建： Maven；统一使用 Wrapper。

代码风格

• 缩进 4 空格；最大行宽 120；UTF-8；Unix 换行；文件末尾保留换行。
• 包名 com.example.app 全小写；类/接口/枚举 PascalCase；方法/变量 camelCase；常量 UPPER_SNAKE_CASE。
• import 不使用通配符；分组顺序：java.*、javax.*、第三方、公司内部，组间空行。
• 注解每行一个；参数较多时每个参数换行对齐。

语言与设计实践

• 可空性：参数尽量非空；需要可空用 @Nullable；返回值可空时优先 Optional<T>（集合返回空集合）。
• 异常：
  • 仅对可恢复情形使用受检异常；不可恢复用 RuntimeException 派生。
  • 禁止吞异常；记录日志并保留根因：throw new FooException("msg", e)。
• 集合与不可变：优先接口类型（List, Map）；尽量使用不可变集合（List.of() / Guava Immutable）。
• 并发：优先 Executors/CompletableFuture/java.util.concurrent; 避免低层 synchronized 共享可变状态。
• 记录日志：使用 SLF4J；结构化日志键值对；禁止输出敏感信息。
• 注释与文档：公共 API 使用 Javadoc（/** … */），首句为概述，包含 @param/@return/@throws。

工程结构

app/
  src/main/java/...
  src/main/resources/...
  src/test/java/...

示例

public final class UserService {
  private final UserRepo repo;

  public UserService(UserRepo repo) { this.repo = Objects.requireNonNull(repo); }

  /** 根据 ID 查询用户，未找到返回 Optional.empty()。 */
  public Optional<User> findById(long id) {
    if (id <= 0) throw new IllegalArgumentException("id must be positive");
    return repo.find(id);
  }
}

测试

• 单元测试覆盖关键分支；使用 Mockito 隔离外部依赖；集成测试使用 Testcontainers。

---

Dart / Flutter 规范

版本与工具

• Dart 3+（空安全）；格式化：dart format；静态检查：dart analyze；测试：dart test/flutter test。

风格与规则

• 行宽 100；缩进 2 空格；字符串默认 单引号；使用 尾随逗号 触发友好换行。
• 命名：类/枚举 PascalCase；成员/变量 lowerCamelCase；常量 lowerCamelCase 或 kPascalCase（团队统一其一）。
• import 使用包前缀；避免相对路径越级；公共库通过 lib/ 暴露 API。

语言实践

• 空安全：用 T?、late 谨慎；尽量用 required 命名参数；返回空集合而非 null。
• 不可变：优先 const 构造与 final 字段；值对象使用 equatable 或 records（Dart 3）。
• 错误处理：UI 层捕获并展示；领域/数据层返回 Result/Either 或抛出受控异常。

Flutter 特定

• build() 保持轻量；提取小部件；避免在 build 里做副作用。
• 状态管理：使用 Provider，全局一致；不可混搭多套范式。
• 主题与可访问性：统一 ThemeData；文字遵循最小触达 44x44；支持深色模式与本地化。

示例

class UserTile extends StatelessWidget {
  const UserTile({super.key, required this.user});
  final User user;

  @override
  Widget build(BuildContext context) {
    return ListTile(title: Text(user.name), subtitle: Text(user.email));
  }
}

工程与测试

• 目录：lib/, test/, integration_test/；导出统一入口 lib/<package>.dart。

安全

• flutter_secure_storage 存放机密；禁用在客户端拼接 SQL。

---

PHP 规范

版本与工具

• PHP 8.3+；启用 declare(strict_types=1);
• 标准：PSR-12（编码风格）、PSR-4（自动加载）。

风格

• 缩进 4 空格；行宽 120；文件使用 <?php，无 close tag；每文件单一类。
• 命名空间必需；类/接口/特性 PascalCase；方法/变量 camelCase；常量 UPPER_SNAKE_CASE。

语言实践

• 类型：所有函数/属性声明类型；返回类型必须标注；尽量使用 readonly/enum。
• 错误处理：仅在边界层捕获并转换为 HTTP/CLI 语义；日志使用 Monolog；禁止 @ 错误抑制。
• 依赖注入：框架（如 Laravel/Symfony）遵循容器注入；禁止在构造中做重 IO。

示例

<?php declare(strict_types=1);

namespace App\Service;

final class UserService {
    public function __construct(private UserRepo $repo) {}

    /** @return list<User> */
    public function list(): array {
        return $this->repo->all();
    }
}

安全

• 使用 PDO/ORM 预处理；绝不拼接 SQL；password_hash/password_verify；默认关闭 display_errors，仅记录日志。

测试

• PHPUnit + Testdouble；对控制器使用特性/内核测试（框架自带）。

---

C# / .NET 规范

版本与工具

• .NET 8.0+；启用 Nullable Reference Types；项目使用 SDK-style csproj。
• 格式化：dotnet format；分析器：Roslyn + StyleCop.Analyzers；测试：xUnit（首选）或 NUnit/MSTest。

风格

• 文件作用域命名空间：namespace Foo.Bar;
• 命名：类型/属性/方法 PascalCase；局部/参数 camelCase；私有字段 _camelCase；常量 PascalCase。
• var 用于显而易见类型；async 方法以 Async 结尾，返回 Task/Task<T>。
• using 顶部排序；启用顶级语句仅限简单程序。

语言与设计

• 优先 记录（record） 表示不可变值对象；表达式体成员简化；模式匹配与 switch 表达式提升可读性。
• 依赖注入：Microsoft.Extensions.DependencyInjection；配置通过 Options 模式强类型化。
• 错误处理：显式捕获特定异常；使用 ILogger 结构化日志；禁止空 catch。

示例

public sealed record User(Guid Id, string Name);

public sealed class UserService
{
    private readonly IUserRepo _repo;
    public UserService(IUserRepo repo) => _repo = repo ?? throw new ArgumentNullException(nameof(repo));

    public async Task<User?> FindAsync(Guid id, CancellationToken ct) => await _repo.FindAsync(id, ct);
}

安全

• 默认启用 HTTPS/HSTS；参数绑定使用验证特性（FluentValidation/DataAnnotations）；机密用 IConfiguration + Secret Manager/Azure Key Vault。
• 依赖通过 Directory.Packages.props 统一管理；开启 dotnet list package --vulnerable。

测试

• xUnit：遵循 AAA；使用 WebApplicationFactory 做 API 集成测试；使用 NSubstitute/Moq。

---

安全与隐私基线（通用）

• 秘密管理：禁止将密钥/令牌写入仓库；使用环境变量与密钥管理服务（Vault/Key Vault/Secrets Manager）。
• 日志脱敏：邮箱、手机号、身份证、token、cookie 等敏感字段做掩码；遵循最小留存周期。
• 依赖治理：启用锁文件（go.sum/composer.lock/gradle.lockfile/Directory.Packages.props），定期更新并审计。
• 输入校验：所有外部输入均视为不可信，进行白名单/模式/长度校验。
• 传输安全：默认 HTTPS/TLS1.2+；启用 HSTS/CSRF 防护/同源策略；Cookie 设置 HttpOnly、Secure、SameSite。

---

代码评审清单（适用于所有 PR）

1. 语义：命名准确、注释到位、公共 API 有文档。
2. 架构：单一职责、模块边界清晰、依赖方向正确、可测试性良好。
3. 风格：符合对应语言规范；无“魔法数”；函数不超长；重复代码已抽取。
4. 错误与边界：错误处理全面；边界条件测试齐全；超时/重试/幂等等策略明确。
5. 安全：输入校验、权限校验、敏感信息保护、依赖与许可证合规。
6. 性能：无不必要的 I/O/分配；关键路径有基准或指标。
7. 可维护性：日志可观测、告警/指标完善、特性开关与回滚预案。