Well404的妙妙屋

【NoneBot2】第二章：基础插件编写指南第一节———前置知识

  • 2022-02-11
  • 作者 Well404
  • ~4.24K 字
  1. 1. python基础
    1. 1.0.0.1. python程序语言设计（视频及网站：中国大学Mooc）
      1. 1.0.0.1.1. 优点:
      2. 1.0.0.1.2. 缺点：
    2. 1.0.0.2. 孙兴华zz（视频：B站）
      1. 1.0.0.2.1. 优点:
      2. 1.0.0.2.2. 缺点：
    3. 1.0.0.3. 菜鸟教程（网站：网站）
      1. 1.0.0.3.1. 优点:
      2. 1.0.0.3.2. 缺点：
  • 2. nonebot的目录结构
    1. 2.0.1. 常规文件
      1. 2.0.1.0.1. src文件夹（或以机器人的名字命名的文件夹）
      2. 2.0.1.0.2. .env.* 文件
      3. 2.0.1.0.3. bot.py 文件
      4. 2.0.1.0.4. pyproject.toml 文件
  • 2.0.2. 其他文件
    1. 2.0.2.0.1. docker相关的文件
    2. 2.0.2.0.2. 其他文件
  • 3. nonebot的插件
    1. 3.1. 插件放在哪？
      1. 3.1.0.0.1. site-packages
      2. 3.1.0.0.2. scr/plugins
  • 3.2. 插件的结构
    1. 3.2.0.0.1. 模块(module)
    2. 3.2.0.0.2. 包(package)

    • 在这个章节正式开始之前，我们首先需要为接下来的学习奠定一些基础。

    python基础

    由于nonebot是使用了 asyncio 的异步框架，并且使用了较多语法糖，相对来说并不适合新手入门，因此如果这个是你入门python之后的第一个实践项目，请做好十足的心理准备。
    在此推荐几个个人入门看的python教程

    python程序语言设计（视频及网站：中国大学Mooc）

    https://www.icourse163.org/course/BIT-268001

    优点:
    1. 北京理工大学出品，国家精品课程，目前仍在开课
    2. 面向非程序员，零基础人群
    3. 完全免费，没有第三方网站付费才能解锁题库啥的骚操作
    4. 节奏把控很好，能在短时间内快速上手
    5. 有配套练习
    6. 有专门的老师可以帮助答疑
    缺点：
    1. 第二周的课程实际完全用不到，属于是为了迎合大学课程特地加的一节，完全没必要去听
    2. 课程深度很浅，基本上就只是半只脚入了门的水平，不足以读懂大部分项目的文档（但是能看懂部分教程）
    3. 课程开始时间为2018年，可能已经部分过时了
    4. 如果只学这一个课程的话，可能无法看懂本教程的部分内容，完全不足以看懂官方文档。
    孙兴华zz（视频：B站）

    https://www.bilibili.com/video/BV1HE41157bu

    优点:
    1. 讲的非常简单易懂
    2. 面向非程序员，零基础人群
    3. 完全免费，没有第三方网站付费才能解锁题库啥的骚操作
    4. python相关教程很多，可以作为入门项目的库有不少
    缺点：
    1. 代码采用了大量中文变量，以及并不十分规范的格式，如果照抄有可能会被大佬嫌弃
    2. 深度并不足以阅读nonebot的源码，但是完全可以看懂此教程。
    3. python教程以及有段时间没更了，估计以后接着更的可能性也不高
    菜鸟教程（网站：网站）

    https://www.runoob.com/python3/python3-tutorial.html

    优点:
    1. 基础部分十分全面，进阶部分也有代码示例等
    2. 十分适合作为速查手册辅助学习
    3. 目前国内面对新手的教程向网站中最好的
    4. 适合有编程基础的快速上手
    缺点：
    1. 没有视频以及答疑
    2. 不适合完全没接触过编程的小白硬啃，需要配合上面的视频教程使用

    nonebot的目录结构

    nonebot的目录结构其实并不复杂，按照 官方文档 中的示例，我们可以看到如下的结构：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    AweSome-Bot
    ├── awesome_bot # 或是 src
    │   └── plugins
    ├── .env # 可选的
    ├── .env.dev # 可选的
    ├── .env.prod # 可选的
    ├── .gitignore
    ├── bot.py
    ├── docker-compose.yml
    ├── Dockerfile
    ├── pyproject.toml
    └── README.md

    我们可以把项目的文件分为如下两类：

    常规文件

    顾名思义，常规结构（当然有一些使用nonebot的单文件机器人）中机器人运行中不可或缺的文件，或是常规结构中无法直接删除的文件等。

    src文件夹（或以机器人的名字命名的文件夹）

    该文件夹是我们用于放置插件的文件夹，这个文件夹可以随意起名，甚至不是必须存在的，但为了代码的规范以及目录结构的工整，官方的指导建议是将插件放置于 src/plugins 文件夹下。
    如果没有特殊情况，个人建议按照官方的建议，将插件放置在指定位置，并且使用 scr 作为其名字而不是机器人的名字，例如 awesome_bot（上面的那个案例就是反例）。
    这样做的目的是为了达到较高的兼容性，否则部分依赖于路径的插件会无法正常工作

    .env.* 文件

    注意：
    在部分操作系统下，以 . 为首的文件会被隐藏，因此，我们需要一些设置才能直接看到这些文件，具体方法请善用搜索引擎自行查找。

    顾名思义，用于储存环境变量的文件，其中 .env 文件一般用于指向另外两个文件。其中的内容一般为 ENVIRONMENT=prod 或 ENVIRONMENT=dev 中的一种，分别指向下面介绍的两个配置文件。

    实际上，你可以在 .env 中直接填写配置，而不需要指向另外两个配置文件。在指向另外的文件的时候，.env 中的内容也会被添加至环境变量一同加载。如果配置文件中的内容有所冲突，此处可参考 官方文档 对此的描述:

    bot.py 文件( nonebot.init ) > 系统环境变量 > .env, .env.* 文件

    .env.prod 文件是用于 生产环境 的环境变量存储，也就是日常使用的环境。
    .env.dev 文件是用于 测试环境 的环境变量存储，也就是编写插件或者其他测试的时候使用的，一般来说会开启一些实验性功能以及更加详细的log，能为我们debug提供更多信息。

    注意：
    这两个文件中起决定性差距的并不是文件名，而且其中的内容，例如你可以在 .env.prod 中开启debug模式，也可以不在 .env.dev 中开启任何测试性内容。
    但从实际出发，个人是十分不推荐这么做的，请务必不要这么做！！！

    在实际使用中，我们一般来说可以把无论哪个环境都需要加载的环境变量填写到 .env 中，对于某种特定环境变量填写在对应的环境变量中。

    bot.py 文件

    相当于机器人的心脏，在这个文件中执行了机器人的初始化以及插件加载等操作。
    由于其中的代码与其他文件和其他插件有较强的的关联性，因此不在此单独说明。

    pyproject.toml 文件

    项目插件配置文件，一般来说是存储一些项目信息的文件，包括自动导入插件等操作。
    在 bot.py 中对应的加载代码为 nonebot.load_from_toml("pyproject.toml")

    重要
    以下纯属依据我浅薄的经验得出的个人观点，希望各位结合实际合理选择操作方法，而不是单纯听信我的一家之言，盲目反对官方的目录结构安排不合理。

    但我个人是并不建议使用这个文件进行自动导入的，理由如下：

    1. 我们可以用其他更加直观可控的方法进行插件加载等操作，例如 nonebot.load_plugin('插件名字')
    2. 这个文件是配合 nb-cli 中提供的脚手架进行使用的，相对第一条中的方法有编辑器进行语法提示来说有更高的翻车风险。
    3. 最重要的一点，在部分环境下，pyproject.toml 并不能正常的导入插件（详细可见视频），也就是在不同的环境下可能会导致完全不一样的结果。

    因此，我一般会在 bot.py 中直接将 nonebot.load_from_toml("pyproject.toml") 这行代码直接注释掉或删除。

    其他文件

    在常规的部署方法下，该部分的文件可直接删除，而不会对机器人的正常使用造成任何影响。

    docker相关的文件

    docker-compose.yml 以及 Dockerfile
    官方提供的 docker 支持，在之后可能会出的docker部署教程会介绍。

    其他文件

    .gitignore 以及 README.md
    类似于谁都不会看的说明书吧，对机器人来说没什么用。 (￣ε(#￣)

    nonebot的插件

    官方文档中对插件的介绍
    假如说使用nonebot搭建的机器人是一个人的话，nonebot可以理解为这个机器人的身体，能够做出各种各样的行为，但并不能产生自我意识。而插件则是这个人体中的“意识”，仅凭自己是无法独立存在的，但可以依赖身体做出行为，对身体进行指导。

    插件放在哪？

    理论上，你放在哪里都可以，就像你可以把Windows中的程序安装在任何系统允许的位置。
    但从可读性以及历史角度出发，nonebot中的插件一般来说有两个相对固定的存放位置

    site-packages

    也就是python的第三方库的存放位置，这里可以直接使用 nonebot.load_plugin() 来进行载入，一般来说，你从插件商店下载的插件就会存在这里。

    scr/plugins

    上文中提及到的目录，在此不再次赘述。可以使用 nonebot.load_plugins("src/plugins") 来加载该文件夹中的插件。

    注意！
    如果插件的名字首个字符是 _ 的话，那么这个插件将不会被 “自动加载” ，但仍可以使用单独加载的方式进行载入。

    插件的结构

    在nonebot中，插件可以以模块(module)或包(package)的形式导入，这个相信对于编写过多文件脚本的同学并不陌生，这里的模块形式和包形式与python中的定义一致。

    模块(module)

    也就是单文件形式的python脚本，例如下方展示的名为 my_plugin 的插件。

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    AweSome-Bot
    ├── src
    │   └── plugins
    |      └── my_plugin.py
    ├── .env
    ├── .env.dev
    ├── .env.prod
    ├── .gitignore
    ├── bot.py
    ├── docker-compose.yml
    ├── Dockerfile
    ├── pyproject.toml
    └── README.md

    相对于包形式的插件，模块形式的插件更简单，但相对的只能在一个文件中塞下全部代码，因此除非十分简单的插件，不建议使用该形式。

    包(package)

    以一个文件夹形式存在的包，例如下方展示的名为 my_plugin 的插件。

    值得注意的是，在python中，一个合法的包中必须含有一个 __init__.py ，即便其中一个字都没有也不能省略。

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    AweSome-Bot
    ├── src
    │   └── plugins
    |      └── my_plugin
    |         └── __init__.py
    |         └── function.py
    ├── .env
    ├── .env.dev
    ├── .env.prod
    ├── .gitignore
    ├── bot.py
    ├── docker-compose.yml
    ├── Dockerfile
    ├── pyproject.toml
    └── README.md

    相对于模块形式的插件，包形式的插件更加灵活美观，是个人比较推荐的插件形式。

    本作品采用 知识共享署名-相同方式共享 4.0 国际许可协议 进行许可
    最后编辑：2022-02-14