NeoBot/docs/development-standards.md

NEO Bot 开发规范与公约

写代码很简单，但写出高性能、不炸裂、好维护的代码需要遵守规矩。

本文档定义了 NEO Bot 项目的开发守则、编码公约、注意事项和代码规范。所有贡献者和插件开发者都必须遵循这些规范，确保机器人稳定运行、代码质量统一。

如果你觉得规范太麻烦，可以问问镀铬酸钾，他会给你一对一教学。。。但最好还是遵守规矩。

补充阅读：

• 插件开发最佳实践 - 必读！写插件的基本规矩
• 项目结构 - 了解代码组织
• 核心概念 - 理解框架设计

1. 开发守则（基本原则）

1.1 异步优先原则

• 绝对不要阻塞事件循环：NeoBot 采用单线程异步架构，任何同步阻塞操作都会导致整个机器人卡死。

  • 禁止：time.sleep()、同步 requests、密集 CPU 计算
  • 必须：使用 await asyncio.sleep()、异步 HTTP 客户端、线程池执行同步任务

• 异步任务处理：长时间运行的任务应使用 run_in_thread_pool 或 asyncio.create_task 执行，避免阻塞主循环。

1.2 资源管理原则

• 连接复用：禁止重复创建连接和资源实例。

  • HTTP 请求：使用全局 aiohttp session 或插件提供的 get_session()
  • 浏览器操作：必须通过 browser_manager.get_page() 获取页面实例
  • Redis 连接：通过 redis_manager 单例访问

• 资源池化：浏览器页面、数据库连接等资源必须使用框架提供的池化机制。

1.3 性能优化原则

• 缓存策略：频繁访问的外部数据必须添加缓存。

  • 短期缓存（<1小时）：使用 Redis 或内存缓存
  • 长期缓存：考虑持久化存储

• 懒加载：大型资源或初始化成本高的组件应延迟加载。

1.4 错误处理原则

• 异常捕获：所有插件代码都应妥善处理异常，避免插件崩溃影响机器人运行。
• 友好提示：向用户返回清晰、友好的错误信息，避免暴露内部细节。
• 日志记录：所有重要操作和错误都应记录日志，使用 ModuleLogger 进行结构化日志记录。

1.5 安全性原则

• 输入验证：所有用户输入都必须验证和清理，防止注入攻击。
• 代码执行安全：使用沙箱环境执行用户代码，隔离系统资源。
• 权限控制：严格遵循权限管理系统，禁止越权操作。

1.6 跨平台兼容性原则

NEO Bot 需要在 Windows 开发环境和 Linux 生产环境中都能正常运行。

• 路径处理：

  • 使用 pathlib.Path 处理文件路径，避免手动拼接字符串。
  • 使用 / 作为路径分隔符（Python 会自动转换）。
  • 禁止使用硬编码的路径分隔符（如 \\ 或 /）。

• 系统依赖：

  • 避免使用平台特定的系统调用。
  • 如果必须使用，通过 sys.platform 检测平台并提供备选方案。

• 环境变量：

  • 通过 global_config 获取配置，而不是直接读取环境变量。
  • 敏感信息（如 API 密钥）必须通过配置管理。

• 文件权限：

  • 在 Linux 上注意文件权限设置，确保 Bot 有读写权限。
  • 临时文件应放在系统临时目录（tempfile.gettempdir()）。

2. 公约（编码约定）

2.1 项目结构公约

• 插件位置：所有插件必须放置在 plugins/ 目录下，单个 .py 文件或包含 __init__.py 的目录。
• 模块导入：遵循标准导入顺序：标准库 → 第三方库 → 本地模块。
• 配置访问：通过 global_config 单例访问配置，禁止硬编码配置值。

2.2 单例管理器使用公约

NEO Bot 的核心是单例管理器（core/managers/ 目录下的类）。所有全局资源都必须通过管理器访问。

• 禁止重复创建：严禁自己实例化管理器类，必须通过导入的单例对象访问。

  • ✅ from core.managers.redis_manager import redis_manager
  • ❌ RedisManager() （错误！会创建新实例）

• 资源池化：浏览器页面、数据库连接等资源必须使用管理器提供的池化接口。

  • ✅ await browser_manager.get_page()
  • ❌ playwright.chromium.launch() （错误！会创建新浏览器进程）

• 数据一致性：单例管理器确保全局数据一致性，不要绕过管理器直接操作底层资源。

2.2.1 单例模式实现机制

NEO Bot 提供了两种单例模式实现方式，位于 core/utils/singleton.py：

1. Singleton 基类（继承方式）

from core.utils.singleton import Singleton

class MyManager(Singleton):
    """通过继承 Singleton 基类实现单例"""
    
    def __init__(self, config: dict):
        """
        初始化管理器
        
        Args:
            config: 配置字典
        """
        # 调用父类 __init__ 确保单例初始化
        super().__init__()
        
        # 检查是否已经初始化（防止 __init__ 被多次调用）
        if hasattr(self, '_my_initialized') and self._my_initialized:
            return
            
        # 执行一次性初始化逻辑
        self.config = config
        self.resource = None
        self._initialize_resource()
        
        # 标记为已初始化
        self._my_initialized = True
    
    def _initialize_resource(self):
        """初始化资源（只执行一次）"""
        self.resource = initialize_resource(self.config)
    
    async def cleanup(self):
        """清理资源（单例管理器应实现清理方法）"""
        if self.resource:
            await self.resource.close()

特性：

• 通过重写 __new__ 方法确保每个类只有一个实例
• 自动处理重复初始化问题，但建议子类添加额外的初始化检查
• 使用全局字典存储实例，避免类型检查问题
• 支持带参数的 __init__ 方法

2. @singleton 装饰器（装饰器方式）

from core.utils.singleton import singleton

@singleton
class MyManager:
    """通过装饰器实现单例"""
    
    def __init__(self, config):
        self.config = config
        self.resource = None
    
    async def initialize(self):
        self.resource = await load_resource()

特性：

• 将普通类转换为单例类，无需修改类继承关系
• 保持原始类的元数据（名称、文档字符串等）
• 适用于无法修改基类的现有类

3. 使用建议

• 新管理器类：优先使用 Singleton 基类继承方式，结构更清晰
• 现有类转换：使用 @singleton 装饰器，无需重构
• 线程安全：两种方式都假设在单线程异步环境中使用，如需线程安全请自行加锁
• 导入方式：单例类应该通过模块级别的实例变量导出，如：

  # redis_manager.py
  class RedisManager(Singleton):
      ...
  
  redis_manager = RedisManager()  # 创建并导出单例实例
  

4. 重要注意事项

• 避免循环导入：单例类的导入应谨慎处理，避免循环依赖
• 初始化时机：单例在第一次导入时创建，确保所需依赖已就绪
• init 调用语义：虽然实例是单例，但 __init__ 方法可能被多次调用（如重新导入时）。应添加额外检查确保一次性逻辑只执行一次。
• 资源清理：单例管理器应在程序退出时清理资源，实现 cleanup() 方法

2.3 命名公约

• 文件命名：使用小写字母和下划线，例如 my_plugin.py。
• 类命名：使用 PascalCase，例如 CommandManager。
• 函数/方法命名：使用 snake_case，例如 handle_message。
• 常量命名：使用 UPPER_SNAKE_CASE，例如 MAX_RETRY_COUNT。
• 变量命名：使用 snake_case，具有描述性，避免单字母变量（循环变量除外）。

2.4 类型提示公约

• 全面使用：所有函数、方法、类属性都应提供类型提示。这是强制要求，因为框架开启了 Mypyc 编译。
• 性能优化：类型提示不仅帮助发现 Bug，还能让 Mypyc 生成更高效的机器码。
• 返回类型：明确指定返回类型，包括 None。
• 复杂类型：使用 typing 模块中的泛型，如 List[str]、Dict[str, Any]。
• 可选参数：使用 Optional[...] 或默认值 = None。

示例：

# 好的写法
async def handle(event: MessageEvent, args: list[str]) -> None:
    ...

# 不好写法（会导致编译警告）
async def handle(event, args):
    ...

2.5 异常处理公约

• 自定义异常：使用框架提供的自定义异常类，避免抛出通用的 Exception。
• 异常链：保留原始异常信息，使用 raise CustomError(...) from e。
• 资源清理：使用 try...finally 或上下文管理器确保资源释放。

2.6 日志记录公约

• 模块化日志：每个模块使用 ModuleLogger("ModuleName") 创建专用日志记录器。
• 日志级别：
  • DEBUG：调试信息，详细操作记录
  • INFO：常规操作记录
  • WARNING：预期内的异常或潜在问题
  • ERROR：操作失败但可恢复的错误
  • CRITICAL：系统级错误，需要立即关注

3. 注意事项（常见陷阱）

3.1 异步编程陷阱

• 忘记 await：异步函数调用必须使用 await，否则任务不会执行。
• 阻塞循环：在异步函数中执行同步阻塞操作会冻结整个事件循环。
• 任务泄漏：创建的异步任务必须被妥善管理，避免内存泄漏。

3.2 资源管理陷阱

• 连接泄漏：未关闭的 HTTP 连接、数据库连接会导致资源耗尽。
• 文件句柄泄漏：打开的文件必须显式关闭或使用上下文管理器。
• 缓存雪崩：大量缓存同时过期可能导致系统负载激增。

3.3 性能陷阱

• N+1 查询：避免在循环中执行数据库或 API 查询，使用批量操作。
• 内存泄漏：大型数据结构长时间驻留内存，应定期清理。
• 重复计算：相同的计算结果应缓存，避免重复计算。

3.4 安全性陷阱

• SQL 注入：使用参数化查询或 ORM，禁止拼接 SQL 字符串。
• XSS 攻击：渲染用户输入时必须进行 HTML 转义。
• 路径遍历：用户提供的文件路径必须进行规范化验证。

4. 代码规范（详细指南）

4.1 文档字符串规范（强制要求）

所有代码必须包含完整的文档字符串，这是项目质量保证的基础。缺少文档字符串的代码将在审查中被拒绝。

• 模块级文档：每个模块顶部应有文档字符串，描述模块功能和主要接口。
• 类级文档：每个类应有文档字符串，描述类的职责、使用方法和示例。
• 函数/方法级文档：每个公共函数和方法必须有文档字符串，包含参数说明、返回值和异常信息。

参数注释要求：

1. 每个参数都必须有类型提示和简要说明
2. 返回值必须明确说明类型和含义
3. 可能抛出的异常必须列出
4. 复杂的函数应提供使用示例

标准格式示例：

def process_data(data: List[str], timeout: int = 30) -> Dict[str, Any]:
    """
    处理数据并返回结果。

    Args:
        data: 待处理的数据列表
        timeout: 操作超时时间，单位秒

    Returns:
        处理结果的字典，包含状态和详情

    Raises:
        TimeoutError: 处理超时时抛出
        ValueError: 数据格式错误时抛出

    Example:
        >>> result = process_data(["item1", "item2"])
        >>> print(result["status"])
    """

4.2 函数设计规范

• 单一职责：每个函数只做一件事，保持功能简洁。
• 参数数量：函数参数不宜过多（建议 ≤5），过多时考虑使用 dataclass 或 TypedDict。
• 默认参数：避免使用可变对象作为默认参数，使用 None 代替。

4.3 类设计规范

• 单一职责：每个类应有明确的单一职责。
• 组合优于继承：优先使用组合而非继承来复用功能。
• 属性访问控制：使用 @property 装饰器控制属性访问，隐藏内部实现。

4.4 错误处理规范

• 错误码统一：使用框架定义的 ErrorCode 枚举，避免自定义魔法数字。
• 错误响应格式：使用 exception_to_error_response 生成统一错误响应。
• 用户友好消息：错误消息应同时包含技术细节（日志）和用户友好提示（界面）。

4.5 测试规范

• 测试覆盖率：核心功能应达到 80% 以上的测试覆盖率。
• 异步测试：使用 pytest-asyncio 进行异步测试。
• 测试隔离：测试用例之间应相互独立，避免依赖执行顺序。

5. 提交与协作规范

5.1 Git 提交规范

• 提交信息格式：遵循 Conventional Commits 规范

  <type>(<scope>): <subject>
  
  <body>
  
  <footer>
  

  • type：feat、fix、docs、style、refactor、test、chore
  • scope：影响的模块或功能区域
  • subject：简洁的描述（50字符以内）
  • body：详细说明（可选）
  • footer：Breaking Changes 或 Issue 引用

5.2 代码审查规范

• 审查重点：功能正确性、代码规范、性能影响、安全性。
• 审查态度：建设性反馈，避免人身攻击。
• 审查时效：24小时内响应审查请求。

5.3 分支管理规范

• 主分支：main 分支始终保持可部署状态。
• 功能分支：从 main 创建，命名格式 feature/简短描述。
• 修复分支：从 main 创建，命名格式 fix/问题描述。

5.4 发布规范

• 版本号：遵循语义化版本控制（SemVer）：主版本.次版本.修订版本
• 更新日志：每次发布都应更新 CHANGELOG.md。
• 向后兼容：非主版本更新应保持 API 向后兼容。

6. 插件开发特别规范

6.1 插件元数据

每个插件必须在文件顶部定义 __plugin_meta__ 字典：

__plugin_meta__ = {
    "name": "插件名称",
    "description": "插件功能描述",
    "usage": "使用说明，包括命令格式和示例",
    "author": "作者名（可选）",
    "version": "版本号（可选）",
}

6.2 命令注册

• 命令前缀：使用配置中定义的前缀，不要硬编码。
• 权限控制：使用 Permission 枚举指定命令权限级别。
• 参数解析：利用框架的自动参数解析功能，避免手动解析。

6.3 插件生命周期

• 初始化：避免在模块级别执行初始化操作，使用函数包装。
• 资源清理：提供清理函数或使用上下文管理器管理资源。
• 错误恢复：插件崩溃后应能优雅恢复，不影响其他插件。

7. 总结

遵循这些规范将确保 NeoBot 项目保持高质量、高性能和高可维护性。所有贡献者都应阅读并理解这些规范，并在代码审查中互相监督执行。

记住：规范不是束缚，而是高效协作的基础。