mailimaili

给麦麦提供使用bilibili账号能力的现代化Python项目，支持异步API调用、模块化设计和完整的配置管理系统。

接口参考

bilibili-API-collect - bilibili API收集整理

其他文档

• 本项目调用bilibili API的指南
• 开发指南 - 项目架构和开发说明

安装

本项目使用 uv 进行依赖管理和项目管理。

安装 uv

# 使用 pip 安装 uv
pip install uv

# 或使用其他方式安装，请参考 uv 官方文档

安装项目

# 克隆项目
git clone <repository-url>
cd mailimaili

# 安装项目及其依赖
uv sync

开发环境设置

# 激活虚拟环境
uv shell

# 运行测试
uv run pytest

# 格式化代码
uv run ruff format .

# 代码检查
uv run ruff check . --fix

配置系统

项目提供了智能的配置管理系统，支持自动配置生成、验证和错误提示。

基础配置

首次运行时，系统会自动从模板创建配置文件：

# 系统会自动创建配置文件（如果不存在）
python -m src.api.example

配置文件结构：

# bilibili API 认证配置
[api]
uid = 123456                    # bilibili用户ID
sessdata = "your_sessdata_here" # 认证令牌（必需）
csrf = "your_csrf_here"         # CSRF令牌（可选）

# 日志系统配置
[logging]
level = "INFO"                  # 日志级别
log_to_file = true             # 是否输出到文件
log_dir = "logs"               # 日志目录
rotation = "10 MB"             # 文件轮转大小
retention = "7 days"           # 日志保留时间
enable_json = false            # 是否启用JSON格式

获取认证信息

1. uid: 访问 bilibili个人主页，URL中的数字即为uid
2. SESSDATA: 浏览器F12 → Application → Storage → Cookies → SESSDATA 字段值
3. csrf: 浏览器F12 → Application → Storage → Cookies → bili_jct 字段值

配置系统特性

• 自动生成: 配置文件不存在时自动从模板创建
• 配置验证: 自动验证必要配置项，提供详细错误提示
• 点分隔访问: 支持 get_config_value('api.sessdata') 点分隔键值访问
• 延迟加载: 智能缓存，避免重复读取文件

配置系统使用示例

from src.utils.config import get_config_value, load_config

# 获取单个配置值
sessdata = get_config_value('api.sessdata')
uid = get_config_value('api.uid')

# 加载完整配置
config = load_config()
api_config = config['api']
logging_config = config['logging']

日志系统

项目基于 loguru 实现了强大的日志系统，支持彩色输出、文件轮转和JSON格式。

日志配置选项

[logging]
level = "INFO"                  # 日志级别：TRACE, DEBUG, INFO, SUCCESS, WARNING, ERROR, CRITICAL
enable_json = false            # 启用JSON Lines格式输出
log_to_file = true             # 输出到文件
log_dir = "logs"               # 日志目录
rotation = "10 MB"             # 轮转策略：文件大小、时间等
retention = "7 days"           # 保留策略：时间、文件数量等
encoding = "utf-8"             # 文件编码

日志系统特性

• 彩色控制台输出: 不同级别日志显示不同颜色
• 双格式支持: 支持文本和JSON两种输出格式
• 智能轮转: 支持按文件大小、时间自动轮转日志文件
• 自动清理: 自动删除过期日志文件
• 模块标识: 每条日志自动标识来源模块

日志使用示例

from src.utils.logger import get_logger, setup_logging

# 获取模块专用的logger
logger = get_logger("my_module")

# 记录不同级别的日志
logger.debug("调试信息")
logger.info("普通信息")
logger.success("成功操作")
logger.warning("警告信息")
logger.error("错误信息")

# 程序化配置日志
setup_logging(
    level="DEBUG",
    log_to_file=True,
    rotation="1 day",
    retention="30 days"
)

日志输出示例

控制台输出（彩色）:

12:34:56.789 | I | my_module      - 操作成功完成
12:34:56.790 | W | my_module      - 检测到异常情况

文件输出:

2024-01-01 12:34:56.789 | INFO     | my_module         | app.py:123 - 操作成功完成
2024-01-01 12:34:56.790 | WARNING  | my_module         | app.py:124 - 检测到异常情况

JSON格式输出:

{"timestamp": "2024-01-01 12:34:56.789", "level": "INFO", "level_no": 20, "module": "my_module", "message": "操作成功完成", "file": "app.py", "line": 123, "function": "main", "process": 12345, "thread": 67890}

项目结构

mailimaili/
├── src/                          # 源代码目录
│   ├── api/                      # API模块
│   │   ├── __init__.py           # 统一API接口
│   │   ├── base.py              # 基类定义
│   │   ├── bilibili_client.py   # 底层HTTP客户端
│   │   ├── example.py           # 使用示例
│   │   └── modules/             # 功能模块
│   │       ├── comment/         # 评论功能
│   │       ├── dynamic/         # 动态功能
│   │       └── message/         # 消息功能
│   └── utils/                   # 工具模块
│       ├── config.py            # 配置管理
│       └── logger.py            # 日志管理
├── tests/                        # 测试目录
├── doc/                         # 文档目录
├── config.toml                  # 配置文件（运行时自动创建）
├── config-template.toml        # 配置模板
├── pyproject.toml              # 项目配置
└── README.md                   # 项目说明

快速开始

1. 环境准备

# 安装项目依赖
uv sync

# 激活虚拟环境
uv shell

2. 配置认证

首次运行时系统会自动创建配置文件并提示配置：

python -m src.api.example

按照提示编辑 config.toml，配置 bilibili 认证信息。

3. 运行示例

# 测试动态API
python -m src.api.example

# 运行测试
uv run pytest

# 代码检查
uv run ruff check . --fix

开发指南

API使用模式

from src.api import BilibiliAPI
from src.utils.config import get_config_value
from src.utils.logger import get_logger
import asyncio

logger = get_logger("my_app")

async def main():
    # 从配置加载认证信息
    sessdata = get_config_value('api.sessdata')
    uid = get_config_value('api.uid')

    cookies = {"SESSDATA": sessdata}

    async with BilibiliAPI(cookies=cookies) as api:
        # 获取用户动态
        dynamics = await api.dynamic.get_dynamic_list(host_mid=uid)
        logger.info(f"获取到 {len(dynamics.get('items', []))} 条动态")

        # 获取未读消息
        messages = await api.message.get_unread_msg_count()
        logger.info(f"未读消息数: {messages}")

if __name__ == "__main__":
    asyncio.run(main())

错误处理

try:
    async with BilibiliAPI(cookies=cookies) as api:
        result = await api.dynamic.get_dynamic_list(host_mid=uid)
except ValueError as e:
    logger.error(f"配置错误: {e}")
except Exception as e:
    logger.error(f"API调用失败: {e}")