10.2.2 创建扩展对象

shell.createExtensionObject()要创建新的扩展对象以提供一个或多个函数、数据类型或更多扩展对象,请使用JavaScript 或shell.create_extension_object() Python 中的内置 函数:

shell.createExtensionObject()

shell.addExtensionObjectMember()要向扩展对象添加成员,请使用JavaScript 或 shell.add_extension_object_member()Python 中的内置 函数:

shell.addExtensionObjectMember(object, name, member[, definition])

在哪里:

  • object是要添加新成员的扩展对象。

  • name是新成员的名字。该名称必须是有效的脚本标识符,因此第一个字符必须是字母或下划线字符,后跟任意数量的字母、数字或下划线字符。该名称在已添加到同一扩展对象的成员中必须是唯一的,并且如果该成员是一个函数,则该名称不必与已定义函数的名称相匹配。即使您使用 Python 来定义和添加成员,名称也最好以驼峰式命名。在驼峰式中指定成员名称使 MySQL Shell 能够自动强制执行命名约定。MySQL Shell 使用驼峰大小写使成员在 JavaScript 模式下可用,

  • member是新成员的值,可以是以下任何一种:

    • 受支持的基本数据类型。支持的数据类型是 nonenullboolnumber(整数或浮点数)、stringarraydictionary

    • JavaScript 或 Python 函数。您可以在作为成员添加到扩展对象的函数主体中使用本机代码,前提是接口(参数和返回值)仅限于表 10.1“扩展对象支持的数据类型对”中支持的数据类型. 在接口中使用其他数据类型会导致未定义的行为。

    • 另一个扩展对象。

  • definition是一个可选的字典,它可以包含成员的帮助信息,如果成员是函数,则还包含函数接收的参数列表。帮助信息使用以下属性定义:

    • brief是成员的简短描述。

    • details是成员的详细描述,以字符串列表的形式提供。这是在您使用 MySQL Shell \help命令时提供的。

    函数的参数使用以下属性定义:

    • parameters是描述函数接收的每个参数的字典列表。每个字典描述一个参数,并且可以包含以下键:

      • name(字符串,必需):参数的名称。

      • type(string, required): 参数的数据类型,stringintegerboolfloatarraydictionaryobject之一。如果类型是object, 也可以使用classor键。classes如果类型是 string,values 密钥也可以使用。如果类型是 字典options也可以使用key。

      • class(字符串,可选,当数据类型为对象时允许):定义允许作为参数的对象类型。

      • classes(字符串列表,可选,当数据类型为object时允许):定义允许作为参数的对象类型的类列表。class和 的受支持对象类型 classes是 MySQL Shell API 公开的对象类型,例如 SessionClassicSessionTableCollection。如果将对象类型传递给不在此列表中的函数,则会引发错误。

      • values(字符串列表,可选,当数据类型为字符串时允许):对参数有效的值列表。如果将值传递给不在此列表中的函数,则会引发错误。

      • options(选项列表,可选,数据类型为字典时允许):参数允许的选项列表。选项使用与参数相同的定义结构,但如果 required未为选项指定,则默认为false. MySQL Shell 验证最终用户指定的选项,如果将选项传递给不在此列表中的函数,则会引发错误。在 MySQL Shell 8.0.17 到 8.0.19 中,数据类型为“ dictionary时需要此参数,但从 MySQL Shell 8.0.20 开始它是可选的。如果您创建一个没有选项列表的字典,则最终用户为该字典指定的任何选项都将由 MySQL Shell 直接传递给该函数,而无需验证。

      • required(bool, optional):参数是否必填。如果 required没有为参数指定,则默认为true.

      • brief(字符串,可选):作为帮助信息提供的参数的简短描述。

      • details(字符串列表,可选):作为帮助信息提供的参数的详细描述。

扩展对象被认为正在构建中,直到它被注册为 MySQL Shell 全局对象,或作为成员添加到另一个已注册为 MySQL Shell 全局对象的扩展对象。如果您尝试在 MySQL Shell 中使用尚未注册的扩展对象,则会返回错误。

跨语言注意事项

扩展对象可以包含 Python 中定义的成员和 JavaScript 中定义的成员的混合。MySQL Shell 管理数据从一种语言到另一种语言的传输,作为参数和返回值。 表 10.1,“扩展对象支持的数据类型对”显示了 MySQL Shell 在语言之间传输数据时支持的数据类型,以及用作彼此表示的对:

表 10.1 扩展对​​象支持的数据类型对

JavaScript Python
布尔值 布尔值
细绳 细绳
整数
数字 漂浮
无效的 没有任何
大批 列表
地图 字典

扩展对象在两种语言中实际上是同一个对象。