Skip to content

msra-app-func.md

Latest commit

 

History

History
62 lines (43 loc) · 3.5 KB

msra-app-func.md

File metadata and controls

62 lines (43 loc) · 3.5 KB
Raw

[app.func.]

Таблица [app.func.<id>] описывает одну публичную функцию API. Это основная единица языка: из неё client строит метод, его сигнатуру, транспорт и место в дереве классов.

Ключ Что делает Как влияет на поведение
name Публичное имя метода Становится именем async-метода в client. Значение должно быть статическим; если его не указать, имя метода совпадает с идентификатором таблицы.
transport Способ выполнения Управляет тем, как именно будет отправляться запрос: direct, fetch или goto. Если ключ не задан, функция ведёт себя как fetch.
method HTTP-метод Определяет HTTP-verb запроса. Для direct и fetch метод используется как есть; для goto он запрещён. Если ключ не задан, значение по умолчанию GET.
group Ссылка на группу Помещает функцию в нужный namespace client и определяет, под каким классом она будет доступна. Если ключ не задан, функция остаётся на root-уровне.
description Описание функции Используется как docstring у сгенерированного метода и как подсказка в документации.

transport

Допустимые значения:

  • direct
  • fetch
  • goto

Что меняется

  • direct использует _direct_request: это прямой HTTP-GET через retry-клиент, без page-flow.
  • fetch использует browser-backed _request: запрос идёт через браузерный контекст и наследует referrer/CORS/credentials/headers.
  • goto открывает отдельную страницу, навигирует по URL и затем передаёт результат extractor-у.

method

method принимает один из HTTP-verb-ов:

  • GET
  • POST
  • PUT
  • PATCH
  • DELETE
  • HEAD
  • OPTIONS

Правила

  • Если transport="goto", method нельзя задавать.
  • Если transport="direct" или transport="fetch", method нужен, чтобы generated client знал, какой verb отправлять.
  • transport и method лучше задавать явно, чтобы контракт был однозначным.

group

group связывает функцию с [app.groups.*].

Это влияет на:

  • место функции в дереве классов;
  • структуру generated package;
  • удобство навигации в IDE и в документации;
  • то, какой group-class будет держать метод как атрибут.

description

Описание функции не влияет на runtime, но влияет на читаемость клиентского кода:

  • попадает в docstring метода;
  • помогает IDE показывать смысл метода;
  • делает generated docs заметно полезнее.