SqlAlchemy 2.0 中文文档（三十二）（1）

原文：docs.sqlalchemy.org/en/20/contents.html

排序列表

原文：docs.sqlalchemy.org/en/20/orm/extensions/orderinglist.html

一个管理包含元素的索引/位置信息的自定义列表。

作者：

Jason Kirtland

orderinglist是一个用于可变有序关系的辅助程序。它将拦截对由relationship()管理的集合执行的列表操作，并自动将列表位置的更改同步到目标标量属性。

示例：一个slide表，其中每行引用相关bullet表中的零个或多个条目。幻灯片中的子弹根据bullet表中position列的值按顺序显示。当内存中重新排序条目时，position属性的值应更新以反映新的排序顺序：

Base = declarative_base()
class Slide(Base):
    __tablename__ = 'slide'
    id = Column(Integer, primary_key=True)
    name = Column(String)
    bullets = relationship("Bullet", order_by="Bullet.position")
class Bullet(Base):
    __tablename__ = 'bullet'
    id = Column(Integer, primary_key=True)
    slide_id = Column(Integer, ForeignKey('slide.id'))
    position = Column(Integer)
    text = Column(String)

标准关系映射将在每个Slide上产生一个类似列表的属性，其中包含所有相关的Bullet对象，但无法自动处理顺序变化。将Bullet附加到Slide.bullets时，Bullet.position属性将保持未设置状态，直到手动分配。当Bullet插入列表中间时，后续的Bullet对象也需要重新编号。

OrderingList对象自动化此任务，管理集合中所有Bullet对象的position属性。它是使用ordering_list()工厂构建的：

from sqlalchemy.ext.orderinglist import ordering_list
Base = declarative_base()
class Slide(Base):
    __tablename__ = 'slide'
    id = Column(Integer, primary_key=True)
    name = Column(String)
    bullets = relationship("Bullet", order_by="Bullet.position",
                            collection_class=ordering_list('position'))
class Bullet(Base):
    __tablename__ = 'bullet'
    id = Column(Integer, primary_key=True)
    slide_id = Column(Integer, ForeignKey('slide.id'))
    position = Column(Integer)
    text = Column(String)

使用上述映射，Bullet.position属性被管理：

s = Slide()
s.bullets.append(Bullet())
s.bullets.append(Bullet())
s.bullets[1].position
>>> 1
s.bullets.insert(1, Bullet())
s.bullets[2].position
>>> 2

OrderingList构造仅适用于对集合的更改，而不是从数据库的初始加载，并要求在加载时对列表进行排序。因此，请确保在针对目标排序属性的relationship()上指定order_by，以便在首次加载时排序正确。

警告

当主键列或唯一列是排序的目标时，OrderingList在功能上提供的功能有限。不支持或存在问题的操作包括：

• 两个条目必须交换值。在主键或唯一约束的情况下，这不受直接支持，因为这意味着至少需要先暂时删除一行，或者在交换发生时将其更改为第三个中性值。
• 
  
• 必须删除一个条目以为新条目腾出位置。SQLAlchemy  的工作单元在单次刷新中执行所有 INSERT 操作，然后再执行 DELETE 操作。在主键的情况下，它将交换相同主键的  INSERT/DELETE 以减轻此限制的影响，但对于唯一列不会发生这种情况。未来的功能将允许“DELETE before  INSERT”行为成为可能，从而减轻此限制，但此功能将需要在映射器级别对要以这种方式处理的列集进行显式配置。

ordering_list()接受相关对象的排序属性名称作为参数。默认情况下，对象在ordering_list()中的位置与排序属性同步：索引 0 将获得位置 0，索引 1 位置 1，依此类推。要从 1 或其他整数开始编号，请提供count_from=1。

API 参考

function sqlalchemy.ext.orderinglist.ordering_list(attr: str, count_from: int | None = None, ordering_func: Callable[[int, Sequence[_T]], int] | None = None, reorder_on_append: bool = False) → Callable[[], OrderingList]

准备一个OrderingList工厂，用于在映射器定义中使用。

返回一个适用于作为 Mapper 关系的collection_class选项参数的对象。例如：

from sqlalchemy.ext.orderinglist import ordering_list
class Slide(Base):
    __tablename__ = 'slide'
    id = Column(Integer, primary_key=True)
    name = Column(String)
    bullets = relationship("Bullet", order_by="Bullet.position",
                            collection_class=ordering_list('position'))

参数：

• attr – 用于存储和检索排序信息的映射属性的名称
  
• count_from – 设置从count_from开始的基于整数的排序。例如，ordering_list('pos', count_from=1)将在 SQL 中创建一个基于 1 的列表，将值存储在‘pos’列中。如果提供了ordering_func，则会被忽略。
  

额外的参数传递给OrderingList构造函数。

function sqlalchemy.ext.orderinglist.count_from_0(index, collection)

编号函数：从 0 开始的连续整数。

function sqlalchemy.ext.orderinglist.count_from_1(index, collection)

编号函数：从 1 开始的连续整数。

function sqlalchemy.ext.orderinglist.count_from_n_factory(start)

编号函数：从任意起始位置开始的连续整数。

class sqlalchemy.ext.orderinglist.OrderingList

一个自定义列表，用于管理其子项的位置信息。

OrderingList 对象通常使用 ordering_list() 工厂函数设置，与 relationship() 函数结合使用。

成员

init(), append(), insert(), pop(), remove(), reorder()

类签名

类 sqlalchemy.ext.orderinglist.OrderingList (builtins.list, typing.Generic)

method __init__(ordering_attr: str | None = None, ordering_func: Callable[[int, Sequence[_T]], int] | None = None, reorder_on_append: bool = False)

一个自定义列表，用于管理其子项的位置信息。

OrderingList 是一个 collection_class 列表实现，它将 Python 列表中的位置与映射对象上的位置属性同步。

此实现依赖于列表以正确的顺序开始，因此一定要 确保 在关系上放置一个 order_by。

参数：

• ordering_attr – 存储对象在关系中顺序的属性名称。
  
• ordering_func –
  可选。将 Python 列表中的位置映射到存储在 ordering_attr 中的值的函数。返回的值通常（但不必！）是整数。
  ordering_func 被调用时具有两个位置参数：列表中元素的索引和列表本身。
  如果省略，将使用 Python 列表索引作为属性值。此模块提供了两个基本的预定义编号函数：count_from_0 和 count_from_1。有关诸如步进编号、字母编号和斐波那契编号等更奇特的示例，请参阅单元测试。
  
• reorder_on_append –
  默认为 False。当追加一个具有现有（非 None）排序值的对象时，该值将保持不变，除非 reorder_on_append 为真。这是一种优化，可以避免各种危险的意外数据库写入。
  SQLAlchemy  将在对象加载时通过 append() 将实例添加到列表中。如果由于某种原因数据库的结果集跳过了排序步骤（例如，行 ‘1’ 缺失，但你得到了  ‘2’、‘3’ 和 ‘4’），那么 reorder_on_append=True 将立即重新编号为  ‘1’、‘2’、‘3’。如果有多个会话进行更改，其中任何一个会话恰巧加载了这个集合，即使是临时加载，所有会话都会尝试在它们的提交中“清理”编号，可能会导致除一个之外的所有会话都以并发修改错误失败。
  建议保留默认值为 False，如果你在之前已经排序过的实例上进行append()操作，或者在手动执行 SQL 操作后进行一些清理工作时，只需调用reorder()即可。
  

method append(entity)

将对象追加到列表的末尾。

method insert(index, entity)

在索引之前插入对象。

method pop(index=-1)

移除并返回索引处的项目（默认为最后一个）。

如果列表为空或索引超出范围，则引发 IndexError。

method remove(entity)

移除第一次出现的值。

如果值不存在则引发 ValueError。

method reorder() → None

同步整个集合的排序。

扫描列表并确保每个对象设置了准确的排序信息。

API 参考

function sqlalchemy.ext.orderinglist.ordering_list(attr: str, count_from: int | None = None, ordering_func: Callable[[int, Sequence[_T]], int] | None = None, reorder_on_append: bool = False) → Callable[[], OrderingList]

为映射器定义准备一个OrderingList工厂。

返回一个适合用作 Mapper 关系的collection_class选项参数的对象。例如：

from sqlalchemy.ext.orderinglist import ordering_list
class Slide(Base):
    __tablename__ = 'slide'
    id = Column(Integer, primary_key=True)
    name = Column(String)
    bullets = relationship("Bullet", order_by="Bullet.position",
                            collection_class=ordering_list('position'))

参数：

• attr – 用于存储和检索排序信息的映射属性的名称
  
• count_from – 设置基于整数的排序，从count_from开始。例如，ordering_list('pos', count_from=1)将在 SQL 中创建一个以 1 为基础的列表，在‘pos’列中存储值。如果提供了ordering_func，则忽略。
  

额外的参数将传递给OrderingList构造函数。

function sqlalchemy.ext.orderinglist.count_from_0(index, collection)

编号函数：从 0 开始的连续整数。

function sqlalchemy.ext.orderinglist.count_from_1(index, collection)

编号函数：从 1 开始的连续整数。

function sqlalchemy.ext.orderinglist.count_from_n_factory(start)

编号函数：从任意起始值开始的连续整数。

class sqlalchemy.ext.orderinglist.OrderingList

一个自定义列表，管理其子项的位置信息。

OrderingList对象通常使用与relationship()函数配合使用的ordering_list()工厂函数设置。

成员

init(), append(), insert(), pop(), remove(), reorder()

类签名

类 sqlalchemy.ext.orderinglist.OrderingList (builtins.list, typing.Generic)

method __init__(ordering_attr: str | None = None, ordering_func: Callable[[int, Sequence[_T]], int] | None = None, reorder_on_append: bool = False)

一个自定义列表，用于管理其子项的位置信息。

OrderingList 是一个 collection_class 列表实现，将 Python 列表中的位置与映射对象上的位置属性同步。

此实现依赖于列表以正确顺序开始，因此请务必在关系上放置 order_by。

参数:

• ordering_attr – 存储对象在关系中顺序的属性名称。
  
• ordering_func –
  可选。将 Python 列表��的位置映射到存储在 ordering_attr 中的值的函数。通常返回的值是整数（但不一定是！）。
  ordering_func 被调用时带有两个位置参数：列表中元素的索引和列表本身。
  如果省略，则使用 Python 列表索引作为属性值。本模块提供了两个基本的预构建编号函数：count_from_0 和 count_from_1。有关更奇特的示例，如步进编号、字母和斐波那契编号，请参见单元测试。
  
• reorder_on_append –
  默认为 False。在附加具有现有（非 None）排序值的对象时，该值将保持不变，除非 reorder_on_append 为 true。这是一种优化，可避免各种危险的意外数据库写入。
  当您的对象加载时，SQLAlchemy  将通过 append()  将实例添加到列表中。如果由于某种原因数据库的结果集跳过了排序步骤（例如，行‘1’丢失，但您得到‘2’、‘3’和‘4’），reorder_on_append=True   将立即重新编号项目为‘1’、‘2’、‘3’。如果有多个会话进行更改，其中任何一个碰巧加载此集合，即使是临时加载，所有会话都会尝试在其提交中“清理”编号，可能导致除一个之外的所有会话都因并发修改错误而失败。
  建议保持默认值为 False，并在对先前有序实例进行 append() 操作或在手动 sql 操作后进行一些清理时，只调用 reorder()。
  

method append(entity)

将对象追加到列表末尾。

method insert(index, entity)

在索引之前插入对象。

method pop(index=-1)

移除并返回索引处的项目（默认为最后一个）。

如果列表为空或索引超出范围，则引发 IndexError。

method remove(entity)

移除第一次出现的值。

如果值不存在，则引发 ValueError。

method reorder() → None

同步整个集合的排序。

扫描列表并确保每个对象具有准确的排序信息设置。

水平分片

原文：docs.sqlalchemy.org/en/20/orm/extensions/horizontal_shard.html

水平分片支持。

定义了一个基本的“水平分片”系统，允许会话在多个数据库之间分发查询和持久化操作。

有关用法示例，请参见源分发中包含的水平分片示例。

深度炼金术

水平分片扩展是一个高级功能，涉及复杂的语句 -> 数据库交互以及对非平凡情况使用半公共 API。在使用这种更复杂且  less-production-tested 系统之前，应始终首先考虑更简单的引用多个数据库“分片”的方法，最常见的是每个“分片”使用一个独立的会话。

API 文档

class sqlalchemy.ext.horizontal_shard.ShardedSession

成员

init(), connection_callable(), get_bind()

类签名

类sqlalchemy.ext.horizontal_shard.ShardedSession (sqlalchemy.orm.session.Session)

method __init__(shard_chooser: ShardChooser, identity_chooser: Optional[IdentityChooser] = None, execute_chooser: Optional[Callable[[ORMExecuteState], Iterable[Any]]] = None, shards: Optional[Dict[str, Any]] = None, query_cls: Type[Query[_T]] = <class 'sqlalchemy.ext.horizontal_shard.ShardedQuery'>, *, id_chooser: Optional[Callable[[Query[_T], Iterable[_T]], Iterable[Any]]] = None, query_chooser: Optional[Callable[[Executable], Iterable[Any]]] = None, **kwargs: Any) → None

构造一个 ShardedSession。

参数：

• shard_chooser – 一个可调用对象，传入一个 Mapper、一个映射实例，可能还有一个 SQL 子句，返回一个分片 ID。该 ID 可能基于对象中存在的属性，或者基于某种轮询方案。如果方案基于选择，则应在实例上设置任何状态，以标记它在未来参与该分片。
  
• identity_chooser –
  一个可调用对象，传入一个 Mapper 和主键参数，应返回一个主键可能存在的分片 ID 列表。

在 2.0 版本中更改：identity_chooser 参数取代了 id_chooser 参数。

• execute_chooser –
  对于给定的ORMExecuteState，返回应发出查询的 shard_ids 列表。从所有返回的 shards 中返回的结果将合并到一个列表中。
  在 1.4 版本中更改：execute_chooser参数取代了query_chooser参数。
  
• shards – 一个字符串分片名称到Engine对象的字典。
  

method connection_callable(mapper: Mapper[_T] | None = None, instance: Any | None = None, shard_id: ShardIdentifier | None = None, **kw: Any) → Connection

提供一个用于工作单元刷新过程中使用的Connection。

method get_bind(mapper: _EntityBindKey[_O] | None = None, *, shard_id: ShardIdentifier | None = None, instance: Any | None = None, clause: ClauseElement | None = None, **kw: Any) → _SessionBind

返回此Session绑定的“bind”。

“bind”通常是Engine的实例，除非Session已经明确地直接绑定到Connection的情况。

对于多重绑定或未绑定的Session，使用mapper或clause参数确定要返回的适当绑定。

请注意，当通过 ORM 操作调用Session.get_bind()时，通常会出现“映射器”参数，例如Session.query()中的每个单独的 INSERT/UPDATE/DELETE 操作，在Session.flush()调用中等。

解析顺序为：

1. 如果提供了映射器并且Session.binds存在，则首先基于正在使用的映射器，然后基于正在使用的映射类，然后基于映射类的__mro__中存在的任何基类，从更具体的超类到更一般的超类进行绑定定位。
   
2. 如果提供了子句并且Session.binds存在，则基于在Session.binds中找到的给定子句中存在的Table对象进行绑定定位。
   
3. 如果Session.binds存在，则返回该绑定。
   
4. 如果提供了子句，则尝试返回一个与最终与该子句关联的MetaData绑定。
   
5. 如果提供了映射器，尝试返回一个与最终与该映射器映射的Table或其他可选择对象关联的MetaData绑定。
   
6. 找不到绑定时，会引发UnboundExecutionError。
   

请注意，Session.get_bind() 方法可以在用户定义的 Session 子类上被重写，以提供任何类型的绑定解析方案。请参阅 自定义垂直分区 中的示例。

参数：

• mapper – 可选的映射类或相应的 Mapper 实例。绑定可以首先从与此 Session 关联的“binds”映射中查询 Mapper，其次从 Mapper 映射到的 Table 的 MetaData 中查询绑定。
  
• clause – 一个 ClauseElement（即 select()、text() 等）。如果 mapper 参数不存在或无法生成绑定，则将搜索给定的表达式构造，通常是与绑定的 MetaData 关联的 Table。
  

另请参阅

分区策略（例如每个会话多个数据库后端）

Session.binds

Session.bind_mapper()

Session.bind_table()

class sqlalchemy.ext.horizontal_shard.set_shard_id

语句的加载器选项，用于将特定的分片 id 应用于主查询，以及额外的关系和列加载器。

set_shard_id 选项可以使用任何可执行语句的 Executable.options() 方法应用：

stmt = (
    select(MyObject).
    where(MyObject.name == 'some name').
    options(set_shard_id("shard1"))
)

上面的语句在调用时将限制为主查询的“shard1”分片标识符，以及所有关系和列加载策略，包括像selectinload()这样的急切加载器，像defer()这样的延迟列加载器，以及惰性关系加载器lazyload()。

这样，set_shard_id选项的范围比在Session.execute.bind_arguments字典中使用“shard_id”参数要广泛得多。

2.0.0 版本中的新功能。

成员

init(), propagate_to_loaders

类签名

类sqlalchemy.ext.horizontal_shard.set_shard_id (sqlalchemy.orm.ORMOption)

method __init__(shard_id: str, propagate_to_loaders: bool = True)

构造一个set_shard_id选项。

参数：

• shard_id – 分片标识符
  
• propagate_to_loaders – 如果保持默认值True，则分片选项将适用于诸如lazyload()和defer()之类的惰性加载器；如果为 False，则该选项不会传播到加载的对象。请注意，defer()在任何情况下始终限制为父行的 shard_id，因此该参数仅对lazyload()策略的行为产生净效果。
  

attribute propagate_to_loaders

如果为 True，则表示此选项应该在“次要”SELECT 语句中传递，这些语句发生在关系惰性加载器以及属性加载/刷新操作中。

class sqlalchemy.ext.horizontal_shard.ShardedQuery

与ShardedSession一起使用的查询类。

遗留特性

ShardedQuery是遗留Query类的子类。 ShardedSession现在通过ShardedSession.execute()方法支持 2.0 风格的执行。

成员

set_shard()

类签名

类sqlalchemy.ext.horizontal_shard.ShardedQuery (sqlalchemy.orm.Query)的构造函数

method set_shard(shard_id: str) → Self

返回一个新的查询，限制为单个分片 ID。

返回的查询的所有后续操作将针对单个分片执行，而不考虑其他状态。

分片 ID 可以传递给 Session.execute() 的 bind_arguments 字典，以进行 2.0 样式的执行：

results = session.execute(
    stmt,
    bind_arguments={"shard_id": "my_shard"}
)

API 文档

class sqlalchemy.ext.horizontal_shard.ShardedSession

成员

init(), connection_callable(), get_bind()

类签名

类sqlalchemy.ext.horizontal_shard.ShardedSession (sqlalchemy.orm.session.Session)的构造函数

method __init__(shard_chooser: ShardChooser, identity_chooser: Optional[IdentityChooser] = None, execute_chooser: Optional[Callable[[ORMExecuteState], Iterable[Any]]] = None, shards: Optional[Dict[str, Any]] = None, query_cls: Type[Query[_T]] = <class 'sqlalchemy.ext.horizontal_shard.ShardedQuery'>, *, id_chooser: Optional[Callable[[Query[_T], Iterable[_T]], Iterable[Any]]] = None, query_chooser: Optional[Callable[[Executable], Iterable[Any]]] = None, **kwargs: Any) → None

构造一个 ShardedSession。

参数:

• shard_chooser – 一个可调用对象，传入 Mapper、映射实例和可能的 SQL 子句，返回一个分片 ID。此 ID 可能基于对象中存在的属性，或者基于某种循环选择方案。如果方案基于选择，则应在实例上设置将来标记其参与该分片的任何状态。
  
• identity_chooser –
  一个可调用对象，传入 Mapper 和主键参数，应返回此主键可能存在的分片 ID 列表。

在 2.0 版本中更改：identity_chooser 参数取代了 id_chooser 参数。

• execute_chooser –
  对于给定的ORMExecuteState，返回应发出查询的分片 ID 列表。返回的所有分片的结果将合并为单个列表。
  在 1.4 版本中更改：execute_chooser 参数取代了 query_chooser 参数。
  
• shards – 一个字符串分片名称到Engine 对象的字典。
  

method connection_callable(mapper: Mapper[_T] | None = None, instance: Any | None = None, shard_id: ShardIdentifier | None = None, **kw: Any) → Connection

提供一个用于工作单元刷新过程中使用的Connection。

method get_bind(mapper: _EntityBindKey[_O] | None = None, *, shard_id: ShardIdentifier | None = None, instance: Any | None = None, clause: ClauseElement | None = None, **kw: Any) → _SessionBind

返回此Session绑定的“绑定”。

“绑定”通常是Engine的一个实例，除非Session已经被显式地直接绑定到Connection。

对于多重绑定或未绑定的Session，将使用mapper或clause参数来确定要返回的适当绑定。

请注意，“mapper”参数通常在通过 ORM 操作调用Session.get_bind()时存在，例如Session.query()中的每个单独的 INSERT/UPDATE/DELETE 操作，在Session.flush()调用等。

解析的顺序如下：

1. 如果给定了映射器并且存在Session.binds，则首先基于正在使用的映射器，然后基于正在使用的映射类，然后基于映射类的__mro__中存在的任何基类，从更具体的超类到更一般的超类。
   
2. 如果给定了子句并且存在Session.binds，则基于在Session.binds中找到的给定子句中的Table对象定位绑定。
   
3. 如果存在Session.binds，则返回该绑定。
   
4. 如果给定了子句，则尝试返回与该子句最终相关联的MetaData相关的绑定。
   
5. 如果给定了映射器，则尝试返回与最终与该映射器映射的Table或其他可选择对象相关联的MetaData相关的绑定。
   
6. 找不到绑定时，会引发UnboundExecutionError。
   

注意，Session.get_bind()方法可以在Session的用户定义子类上被覆盖，以提供任何类型的绑定解析方案。 请参阅自定义垂直分区中的示例。

参数：

• mapper – 可选的映射类或对应的Mapper实例。 绑定可以首先通过查阅与此Session关联的“binds”映射，其次通过查阅Mapper映射到的Table关联的MetaData进行绑定。
  
• clause – 一个ClauseElement（例如select()，text()等）。 如果未提供mapper参数或无法生成绑定，则将搜索给定的表达式构造以查找绑定元素，通常是与绑定的MetaData关联的Table。
  

另请参阅

分区策略（例如每个 Session 的多个数据库后端）

Session.binds

Session.bind_mapper()

Session.bind_table()

class sqlalchemy.ext.horizontal_shard.set_shard_id

语句的加载器选项，可将特定的 shard id 应用于主查询以及用于额外的关系和列加载器。

可以使用任何可执行语句的Executable.options()方法应用set_shard_id选项：

stmt = (
    select(MyObject).
    where(MyObject.name == 'some name').
    options(set_shard_id("shard1"))
)

在上述情况下，当调用语句时，主查询以及所有关系和列加载策略，包括诸如selectinload()、延迟列加载器defer()和惰性关系加载器lazyload()等都将限制为“shard1”分片标识符。

这样，set_shard_id选项的范围比在Session.execute.bind_arguments字典中使用“shard_id”参数要广泛得多。

2.0.0 版本中的新功能。

成员

init(), propagate_to_loaders

类签名

类sqlalchemy.ext.horizontal_shard.set_shard_id（sqlalchemy.orm.ORMOption）

method __init__(shard_id: str, propagate_to_loaders: bool = True)

构造一个set_shard_id选项。

参数：

• shard_id – 分片标识符
  
• propagate_to_loaders – 如果保持默认值True，则shard选项将对懒加载器（如lazyload()和defer()）生效；如果为False，则该选项将不会传播到已加载的对象。请注意，defer()无论如何都会限制到父行的shard_id，因此该参数仅对lazyload()策略的行为产生净效果。
  

attribute propagate_to_loaders

如果为True，表示此选项应传递到关系懒加载器以及属性加载/刷新操作中发生的“次要”SELECT 语句。

class sqlalchemy.ext.horizontal_shard.ShardedQuery

与ShardedSession一起使用的查询类。

遗留特性

ShardedQuery是遗留Query类的子类。ShardedSession现在通过ShardedSession.execute()方法支持 2.0 风格的执行。

成员

set_shard()

类签名

类 sqlalchemy.ext.horizontal_shard.ShardedQuery（sqlalchemy.orm.Query）

method set_shard(shard_id: str) → Self

返回一个新的查询，限定在单个分片 ID。

返回的查询的所有后续操作都将针对单个分片进行，而不考虑其他状态。

shard_id 可以传递给 Session.execute() 的 bind_arguments 字典，用于执行 2.0 风格的操作：

results = session.execute(
    stmt,
    bind_arguments={"shard_id": "my_shard"}
)

SqlAlchemy 2.0 中文文档（三十二）（2）https://developer.aliyun.com/article/1562543