云函数

常规的数据读写接口，建议通过配置API的方式提供，云函数一种用于为配置API无法满足的需求编写接口的方式。

按照云函数的使用场景划分，可分为三类：

  1. object 函数，即针对某条数据的操作接口，如为一个商品生成小程序码。
  2. model 函数，即为某个model提供的扩展接口，如收取订单，同步用户等操作。
  3. 批量操作 函数，用于列表中选中的多条数据进行处理的场景。

以上三种函数的编写方式几乎一致，区别仅在于他们接受的参数略有差异。

定义云函数#

首先，在应用根目录下创建functions.py文件，用于编写云函数，写在这个文件下的云函数将会被lightning自动发现。

下面的过程与代码，均发生在应用根目录下functions.py文件里面。

导入lightning_func装饰器#

from lightning.decorators import lightning_func

编写云函数#

以下演示三种云函数的定法，它们的区别主要是函数接受的参数不同：

编写object#

object函数，有一个id参数需要提供：

from lightning_crm.models import Customer
@lightning_func(name="hello", model=Customer)
def hello_customer(user, id, **kwargs):
customer = Customer.objects.get(pk=id)
return f"Greeting to {customer.name}"

编写Modle函数#

model函数无额外的参数需要提供：

@lightning_func(name="send_report", model=Customer)
def send_report(user, **kwargs):
# do some email sending jobs ....

编写批量操作函数#

批量操作函数需要一个ids(id列表)参数：

@lightning_func(name="upgrade_vip", model=Customer)
def upgrade_vip(user, ids, level, **kwargs):
Custumer.objects.filter(id__in=ids).update(level=level)
return 'OK'

以上演示了云函数的编写方式，里面有三个关键点需要掌握：

1. lightning_func 装饰器的使用。

lightning_func 装饰器用于向lightning注册云函数，它接收以下几个参数：

  • name: 必填，云函数名，英文、数字、下划线的组合。在一个model下，必需唯一。

  • model: 指定模型，必填，lightning会把该函数挂载某个model下。

  • login_required:是否要求登录才能调用。默认是True。

  • staff_required:是否要求员工（后台管理员）才能调用，默认是False。

  • superuser_required:是否要求超级管理员才能调用，默认是False。

  • permissions: 所需权限。前三个xxx_required是常见的权限，更多个性化的控限控制可在此定义。该参数接受一个数组，数组元素为字符串或一个权限类：

    • 字符串：即django的auth应用中 Permission 模型的code，可指定有某个Permission的用户才能调用该函数。

    • 权限类：继承于lightning.BasePermission的权限类。该类需要实现以下方法：

      has_permission(self, user, model, func_name, params, request)

      方法返回True代表有权限，False代表无权限。

2. 云函数的参数

云函数要求的参数有：

  1. user, 必须，代表当前用户。
  2. id, 可选，当编写Object函数时，才需要提供该参数。
  3. ids, 可选，当编写批量操作函数时，才需要提供该参数。
  4. **kwargs，必须。lightning需要注入一些额外的参数，如：
    • view_context，请求上下文，通过该上下文可以获得request, view等的访问权限。
  5. 其他，介于user与 **args之间的参数，用户根据需求进行自定义即可，这些参数的值类型应该是可序列化为JSON的类型，包括Python的几种内置数据类型。

3. 云函数返回值

云函数可以返回以下格式：

  1. Python内置数据格式，如str, int, float, bool, datetime，list, dict等，简言之，能够被json.dumps处理的返回值均可。
  2. Django Model实例，返回的实例必须是当前云函数装饰器中同样的Model，否则会出错。
  3. Django QuerySet，返回的QuerySet必须是当前云函数装饰器中同样的Model，否则会出错。
  4. django.http.HttpResponse实例。
  5. django_restframework.response.Reponse实例。
  6. 无返回值。

以下是完整的示例：

from lightning.decorators import lightning_func
from lightning_crm.models import Customer
from lightning import BasePermission
class TestPermission(BasePermission):
def has_permission(self, user, model, func_name, *kwargs):
return user.is_superuser and func_name == 'hello'
@lightning_func(name="hello", model=Customer, permissions=['change_customer', TestPermission])
def hello_customer(user, id, **kwargs):
return f"just say hi to {id}"

使用云函数#

云函数有两种使用方式：

  1. 作为接口调用，云函数的本质是一个接口，所以，可以当作接口来调用。
  2. 在管理界面上，作为单行数据的操作项或模型的全局操作使用。

1. 作为接口#

路径：云函数使用统一规格的请求路径: /basebone/{app_label}__{model_name}/func/，其中app_label与model_name因不同的Model而异，两者之间是双下划线。

方法：POST

请求体：为JSON object，即Content-Type为 application/json，有两个参数：

  • func_name: 云函数名，即使用lightning_func注册时指定的name。
  • params: JSON object, 里面的属性即对应云函数的参数（user与**kwargs之间的参数）。

返回结果：为JSON object，有以下属性:

  • error_code: 字符串，为"0" 代表成功。
  • error_message: 错误消息，当error_code不为"0"时有值。
  • result: 云函数的返回值，经过JSON序列后之后的数据。

2.1 作为行操作项#

行操作项是指在管理界面的数据表格右侧的操作菜单，即对某一条数据进行操作的选项。lightning的管理页面配置支持调用云函数作为一个操作项，操作步骤如下：

  1. 打开指定Model的页面配置面板，在列表页设置 -> 操作项 一节中，添加操作项，选择云函数，点击确认创建一个新操作。

添加云函数操作

  1. 在操作项列表中展开刚创建的操作，可修改操作名（即菜单名）,函数名填上云函数的名字(lightning_func装饰器里用的name),再填写json object参数，lightning会自动增加id字段到该参数里面。

配置云函数

  1. 保存配置即可看到操作菜单新增了一项。

新操作项

  1. 此时，在表格上任意一行上点击新建的操作项，该操作将调用指定的云函数，成功后会提示成功并重新加载页面的数据。

操作成功

2.2 作为全局操作项#

全局操作是指在管理界面数据表格左上角的操作按钮，例如新建按钮。lightning的管理页面配置支持调用云函数作为一个全局操作项，操作步骤与行操作项类似，在此不赘述，全局操作项在配置面板的位置：列表页设置 -> 全局操作。添加云函数类型操作后，可以配置调用的云函数及参数。

2.3 作为批量操作项#

全局操作是指在管理界面数据表格左上角的批量操作选项。lightning的管理页面配置支持调用云函数作为一个全局操作项，操作步骤与行操作项类似，在此不赘述，全局操作项在配置面板的位置：列表页设置 -> 批量操作，添加云函数类型操作后，可以配置调用的云函数及参数。

Edit this page