跳转至

v2.0.0

重大变更 (Breaking Changes)

v2.0.0 是一个完全重构的版本，与 v1 版本不兼容。主要变更包括：

1. 架构重构

  • 分离 Engine 和 AsMysql 类
  • 新增 Engine 类：独立的 MySQL 连接引擎，可单独使用
  • AsMysql 类：业务逻辑开发基类，通过 client 属性访问 Engine
  • 这种设计使得连接管理和业务逻辑完全分离

2. Result 类变更

  • 错误属性重命名
  • Result.err → Result.error
  • 更符合 Python 命名规范

3. API 变更

  • 连接方式变更
  • v1: 继承 AsMysql 后自动连接

  • v2: 需要显式创建 Engine 并调用 connect()

  • 执行方式变更

  • v1: AsMysql self.client.execute(...)
  • v2: AsMysql self.client.execute(...) (保持不变，但 client 现在是 Engine 实例)

新功能 (New Features)

1. Engine 类

全新的连接引擎类，提供以下功能：

  • URL 连接字符串支持 

    engine = Engine(url="mysql://user:password@host:port/?charset=utf8mb4")

  • 连接状态监控 

    status = engine.status
# 返回连接池的详细状态信息

  • 灵活的连接管理

  • 支持 async with 上下文管理器
  • 支持 await engine() 语法

  • 支持 await engine 语法

  • 连接池配置

  • min_pool_size: 最小连接数
  • max_pool_size: 最大连接数
  • pool_recycle: 空闲连接回收时间
  • connect_timeout: 连接超时时间

2. Result 类增强

  • 错误信息访问
  • error_no: 获取 MySQL 错误码
  • error_msg: 获取 MySQL 错误信息

  • error: 获取完整的错误异常对象

  • 流式查询支持 

    result = await engine.execute("SELECT * FROM large_table", stream=True)
async for row in result:
    process(row)  # 逐行处理，不占用内存

  • 上下文管理器支持 

    async with engine.execute("SELECT * FROM users") as result:
    data = await result.fetch_all()

  • 异步迭代器支持 

    # 方式一：直接迭代
async for row in engine.execute("SELECT * FROM users"):
    print(row)

# 方式二：迭代 Result
result = await engine.execute("SELECT * FROM users")
async for row in result:
    print(row)

  • 自定义结果类型 

    # 支持 tuple（默认）、dict 或自定义模型类
result = await engine.execute(
    "SELECT * FROM users",
    result_class=dict  # 或自定义 Pydantic 模型
)

3. 执行方法增强

  • execute() 方法
  • 支持 stream 参数：启用流式查询
  • 支持 result_class 参数：指定返回结果类型
  • 支持 commit 参数：控制事务提交

  • 支持多种调用方式：

    • result = await engine.execute(...)
    • async with engine.execute(...) as result:
    • async for item in engine.execute(...):

  • execute_many() 方法

  • 批量执行 SQL 语句
  • 支持相同的参数选项

4. 类型提示

  • 完整的类型提示支持
  • 支持泛型类型（Result[T]）
  • IDE 友好的代码补全

5. 测试

  • 新增 pytest 测试套件
  • 覆盖主要功能场景
  • 支持 Mock 测试

更新 (Updates)

1. 包管理工具

  • 使用 uv 作为包管理工具
  • 更快的依赖安装速度
  • 更好的依赖解析

2. 代码质量

  • 改进代码结构
  • 更好的错误处理
  • 更清晰的文档字符串

核心特性 (Features)

v2 版本保留了 v1 版本的核心特性：

  1. 简易使用
  2. asmysql 是对 aiomysql 封装的简易使用库

  3. 提供更友好的 API

  4. 连接池管理

  5. 自动管理 MySQL 连接池
  6. 支持重连机制

  7. 连接池状态监控

  8. 错误处理

  9. 全局自动捕获 MysqlError 错误
  10. 提供错误码和错误信息访问

  11. 优雅的错误处理机制

  12. 执行与获取分离

  13. 执行 SQL 语句和获取结果分离
  14. 支持多种数据获取方式

  15. 灵活的结果处理

  16. 类型提示

  17. 完整的 Python 类型提示
  18. IDE 友好的代码补全

  19. 类型安全

  20. 业务逻辑开发

  21. 直接继承 AsMysql 类进行逻辑开发
  22. 清晰的代码组织
  23. 易于测试和维护