从 flask 服务端代码自动生成客户端代码 -- flask-native-stubs 库介绍

flask-native-stubs 项目灵感来源 swagger 的 codegen 工具. 用来从服务端的路由函数自动生成对应的客户端接口函数.

你将会体验到如同 “本地函数调用” 般的快捷和自然. 如同下面这样:

• 服务端代码:

  from flask_native_stubs import app, auto_route
  
  @auto_route()
  def hello_world(a: int, b: bool, c: str) -> str:
      print('received from client side:', a, b, c)
      return 'hello from server side!'
  
  app.run(host='127.0.0.1', port=8080)
  

• 客户端代码:

  # client side
  from flask_native_stubs import setup_client
  # 注: 将 flask_native_stubs 自动生成的代码 (假如叫 "server_stubs.py") 放在能
  # 够导入的地方. 
  from my_lib.server_stubs import hello_world
  
  # 配置 host 和 port 端口.
  setup_client(host='127.0.0.1', port=8080)
  
  # 如同调用一个本地函数一样. 无论是传参写法, 还是 ide 类型提示, 代码补全等功
  # 能, 都完全按照普通函数调用的习惯去实现即可!
  response = hello_world(a=123, b=True, c='hello from client!')
  print(response)  # -> 'hello from server side!'
  

  • 使用 flask_native_stubs 自动生成的代码 (上面代码块中引用的 “server_stubs.py”) 看起来长什么样:

    from flask_native_stubs.stubgen import magic_route
    
    # 这是一个没有任何功能的 "假函数"
    def hello_world(a: int, b: bool, c: str) -> str:
        ...  # 这里就是三个点.
    
    # 最后用 magic_route 魔术方法将本模块的 hello_world 函数嫁接到 request 
    # 装饰器.
    [magic_route(x) for x in ('hello_world',)]
    

运行截图:

什么是存根文件 (stubs)

“stub” 引用自 java j2ee 的 stub 概念:

为屏蔽客户调用远程主机上的对象, 必须提供某种方式来模拟本地对象, 这种本地对象称为存根 (stub). 存根负责接收本地方法调用, 并将它们委派给各自的具体实现对象.

在 python 中, 也有 stub 的概念, 主要用于类型检查的增强体验. (随着 python 类型注解的愈趋完善, 也有人认为 stub 在这方面的作用被削弱了.)

我们借助服务器端原函数的壳, 生成的外形相似但不具备任何真实业务逻辑的 “伪函数”, 将其称为 stubs, 在概念和使用目的上来说与上述是一致的.

如何生成存根文件 (stubs)

生成 flask-native-stubs 的存根文件方法非常简单. 只需将 app.run 改为 app.generate_stubs 即可:

# server side
from flask_native_stubs import app, auto_route

@auto_route()
def hello_world(a: int, b: bool, c: str) -> str:
    print('received from client side:', a, b, c)
    return 'hello from server side!'

# app.generate_stubs(output_dir: str, filenames_map: dict = None)
# args:
# output_dir: 将生成的存根文件放在哪个目录下.
# filenames_map: (可选) 自定义输入和输出文件名. 键是输入的文件路径, 值是输
# 出的文件路径. 
# 路径可以使用相对或绝对路径.
# 使用相对路径时, 输入端是相对于当前工作目录; 输出端是相对于 # output_dir 参数.
app.generate_stubs(
    output_dir='../lib',
    filenames_map={
    
        'server.py': 'server_stubs.py'
    }
)

将生成后的存根文件复制到客户端项目中, 放到客户端能够导入的地方. (比如加入到 sys.path, 或者加入到 PYTHONPATH 环境变量中.)