Files

K2cr2O1 0e04829ac9 refactor(api): 简化 dataclass 转换逻辑并添加好友/群列表缓存

移除冗余的 _safe_dataclass_from_dict 工具函数，直接使用 dataclass 的构造方法
添加 get_friend_list 和 get_group_list 方法的缓存支持
修复 get_version_info 的错误 API 调用

2026-01-23 17:15:44 +08:00

6.2 KiB

Raw Blame History

NeoBot 开发规范

本文档为 NeoBot 项目的官方开发规范，旨在确保代码的高性能、高可读性和高可维护性。所有贡献者都应遵循这些规范。

本文档以 PEP 8 -- Style Guide for Python Code 为基础，并在此之上补充了针对本项目的特定约定。

核心开发原则

1. 异步优先

永远不要阻塞事件循环。任何同步阻塞操作（如 time.sleep()、同步网络请求、大规模文件读写）都会导致整个机器人框架卡死。

应当: 使用 asyncio.sleep()、异步库（如 aiohttp），并通过 asyncio.to_thread 或 run_in_executor 将同步代码移出主事件循环。
禁止: 直接在异步函数中使用任何可能阻塞的同步调用。

1.1 异步优先原则

绝对不要阻塞事件循环：NeoBot 采用多线程异步架构，任何同步阻塞操作都会导致整个机器人卡死。
- 禁止：time.sleep()、同步 requests、密集 CPU 计算
- 必须：使用 await asyncio.sleep()、异步 HTTP 客户端、线程池执行同步任务
应当: 通过框架提供的单例管理器（如 redis_manager, browser_manager）获取和管理资源。
禁止: 自行实例化管理器或在插件中创建独立的资源实例（如 aiohttp.ClientSession）。

3. 错误处理

健壮性是第一要务。插件的异常不应影响框架的稳定运行。

应当: 在插件和业务逻辑中进行充分的 try...except 异常捕获，并向用户返回友好的错误提示。
禁止: 抛出未被捕获的异常，或向用户暴露原始的错误堆栈信息。

4. 跨平台兼容性

代码必须同时兼容 Windows（开发环境） 和 Linux（生产环境）。

应当: 使用 pathlib.Path 处理文件路径，它能自动处理不同操作系统的路径分隔符。
禁止: 硬编码路径分隔符（如 "data\\temp" 或 "data/temp"）。

代码风格规范

1. 命名规范 (PEP 8)

模块 (Module): lower_case_with_underscores.py
包 (Package): lower_case_with_underscores
类 (Class): PascalCase
函数 (Function) / 方法 (Method) / 变量 (Variable): snake_case
常量 (Constant): UPPER_SNAKE_CASE
私有成员: 以单下划线 _ 开头。

2. 类型提示 (PEP 484)

所有函数和方法的签名都必须包含类型提示。这是强制性要求，因为它对 Mypyc 编译和代码可读性至关重要。

应当: 明确指定所有参数和返回值的类型。对于可能返回 None 的情况，使用 Optional[...]。

示例:

async def get_user_data(user_id: int) -> Optional[Dict[str, Any]]:
    # ...

3. 文档字符串 (PEP 257)

所有公开的模块、类、函数和方法都必须拥有文档字符串。

格式: 遵循 Google Python Style Guide 的文档字符串格式。它清晰、简洁且易于阅读。
内容:
- 模块/类: 简要描述其职责和功能。
- 函数/方法:
  - 一行总结其功能。
  - Args:: 描述每个参数的类型和含义。
  - Returns:: 描述返回值的类型和含义。
  - Raises:: (可选) 描述可能抛出的主要异常。

示例:

async def fetch_data(url: str, timeout: int = 10) -> str:
    """Fetches content from a URL.

    Args:
        url: The URL to fetch from.
        timeout: The request timeout in seconds.

    Returns:
        The content of the response as a string.

    Raises:
        asyncio.TimeoutError: If the request times out.
    """
    # ...

4. 导入规范

顺序: 遵循 PEP 8 的建议，将导入分为三组，每组按字母顺序排列：
1. 标准库 (e.g., asyncio, sys)
2. 第三方库 (e.g., aiohttp, loguru)
3. 本项目模块 (e.g., from core.managers import ...)
绝对导入: 优先使用绝对导入路径（from core.utils import ...），避免使用相对导入（from ..utils import ...），以增强代码清晰度。

5. 日志记录

应当: 使用 from core.utils.logger import logger 获取全局日志记录器实例。在需要区分模块来源时，可以使用 ModuleLogger("MyModule")。
日志级别:
- DEBUG: 用于详细的诊断信息。
- INFO: 用于记录常规的操作流程。
- WARNING: 用于表示发生了预期内的小问题，或提示潜在风险。
- ERROR: 用于记录影响功能但程序仍可运行的错误。
- CRITICAL: 用于记录导致程序崩溃的严重错误。

项目特定约定

1. 单例管理器

框架的核心功能由 core/managers/ 下的单例管理器提供。

获取方式: 必须通过导入模块级别的实例来使用，例如 from core.managers.redis_manager import redis_manager。
核心职责: 这些管理器负责维护全局状态和资源池，是确保性能和数据一致性的关键。

2. 配置管理

访问方式: 所有配置项都应通过 from core.config_loader import global_config 来访问。
禁止: 在代码中硬编码任何配置值（如 API 地址、端口、文件路径等）。

3. 插件元信息

每个插件文件都应在顶部定义 __plugin_meta__ 字典，以供帮助系统使用。

__plugin_meta__ = {
    "name": "插件名称",
    "description": "插件功能的简要描述。",
    "usage": "插件的使用方法，例如 `/command [args]`。"
}

Git 提交约定

为了保持提交历史的清晰，我们采用一种简化的提交信息格式：

<type>: <subject>

<type>:
- feat: 新功能
- fix: Bug 修复
- docs: 文档变更
- style: 代码格式调整（不影响逻辑）
- refactor: 代码重构
- test: 添加或修改测试
- chore: 构建过程或辅助工具的变动
<subject>:
- 对本次提交的简明扼要的描述。
- 使用祈使句，例如 add user authentication 而不是 added user authentication。

示例:

feat: Add /status command to show bot health
fix: Correctly handle empty messages in parser
docs: Update development standards with new guidelines

6.2 KiB Raw Blame History Unescape Escape