Melhores Práticas do DBOS Python

Guia para construir aplicações Python confiáveis e tolerantes a falhas com fluxos de trabalho duráveis do DBOS.

Quando Usar

Consulte estas diretrizes quando:

• Adicionar DBOS a código Python existente
• Criar fluxos de trabalho e etapas
• Usar filas para controle de concorrência
• Implementar comunicação de fluxo de trabalho (eventos, mensagens, streams)
• Configurar e iniciar aplicações DBOS
• Usar DBOSClient de aplicações externas
• Testar aplicações DBOS

Categorias de Regras por Prioridade

Regras Críticas

Configuração e Lançamento do DBOS

Uma aplicação DBOS DEVE configurar e lançar o DBOS dentro de sua função principal:

import os
from dbos import DBOS, DBOSConfig

@DBOS.workflow()
def my_workflow():
    pass

if __name__ == "__main__":
    config: DBOSConfig = {
        "name": "my-app",
        "system_database_url": os.environ.get("DBOS_SYSTEM_DATABASE_URL"),
    }
    DBOS(config=config)
    DBOS.launch()

Estrutura de Fluxo de Trabalho e Etapa

Fluxos de trabalho são compostos por etapas. Qualquer função que execute operações complexas ou acesse serviços externos deve ser uma etapa:

@DBOS.step()
def call_external_api():
    return requests.get("https://api.example.com").json()

@DBOS.workflow()
def my_workflow():
    result = call_external_api()
    return result

Restrições Chave

• NÃO chame DBOS.start_workflow ou DBOS.recv de uma etapa
• NÃO use threads para iniciar fluxos de trabalho - use DBOS.start_workflow ou filas
• Fluxos de trabalho DEVEM ser determinísticos - operações não determinísticas vão para etapas
• NÃO crie/atualize variáveis globais de fluxos de trabalho ou etapas

Como Usar

Leia os arquivos de regras individuais para explicações detalhadas e exemplos:

references/lifecycle-config.md
references/workflow-determinism.md
references/queue-concurrency.md

Referências

• https://docs.dbos.dev/
• https://github.com/dbos-inc/dbos-transact-py

Limitações

• Use esta habilidade apenas quando a tarefa corresponder claramente ao escopo descrito acima.
• Não trate a saída como substituta para validação específica do ambiente, testes ou revisão de especialistas.
• Pare e peça esclarecimentos se os inputs necessários, permissões, limites de segurança ou critérios de sucesso estiverem ausentes.