Manutenção e documentação dos pontos de extremidade da API de muitos aplicativos em uma arquitetura de microsserviço

Acho que um dos maiores pontos negativos do trabalho com microsserviços é garantir que as APIs estejam bem documentadas e que as APIs não alterem seu comportamento sem afetar os aplicativos downstream. Esse problema se amplifica quando você tem muitos serviços que são interdependentes entre si. Talvez nesse momento você esteja fazendo microsserviços errados, mas eu discordo.

Digamos que herdamos 20 microsserviços pertencentes a equipes diferentes e não há documentação clara sobre qual aplicativo usa qual terminal de API de outro aplicativo. Existe uma maneira prescrita de documentar isso? Inicialmente, pensei em analisar os pontos de extremidade de cada aplicativo e adicioná-los a uma tabela de banco de dados, criando um relacionamento FK entre cada aplicativo e a rota de um aplicativo em uma tabela muitos-para-muitos (quase todos esses são aplicativos rails). Mas não tenho certeza se essa é uma boa maneira de lidar com isso, ou estou reinventando a roda aqui.

Em retrospecto, essa pode ser uma maneira não tão ruim de documentar a interação de aplicativos se você estiver iniciando com microsserviços do zero. Isso apenas reforçaria que uma única fonte de verdade seja mantida por meio do uso de um banco de dados e quaisquer alterações nos pontos de extremidade seriam executadas no aplicativo em conjunto com a alteração no banco de dados. Pensamentos?

Uma grande parte do benefício de uma "arquitetura de microsserviço" é que você não está documentando todos esses relacionamentos. Cada serviço é seu próprio produto. E cada proprietário do serviço é responsável pela operação de seu serviço como um produto independente. Isso pode incluir coisas como:

• Publicando documentos de "marketing", documentos de usuário e logs de alterações (incluindo substituições )
• Fornecer uma maneira para os clientes / consumidores solicitarem recursos / reportarem bugs
• Manutenção de um SLA
• Tornar as atualizações o mais compatível possível com as versões anteriores e alterar as mudanças
• Conhecer e assistir feeds de notícias dos serviços que eles consomem diretamente
• Dependências de poda quando possível
• Descontinuar todo o serviço quando ele se torna irrelevante ou muito caro para manter

E assim por diante.

Acima de tudo, enfatizo, como um dos principais benefícios de um microsserviço, a oportunidade para os proprietários de serviços realmente se concentrarem e se especializarem na "única coisa" que seu serviço faz.

Quanto a onde cada proprietário de produto ou serviço deve documentar suas próprias dependências - isso deve acontecer "naturalmente" à medida que são adicionados à configuração do compilador (ou script de construção). Se você precisar saber do que o ServiceA depende, ServiceA/Configuration.xml(ou o que seja ) lhe dirá. Normalmente, eu também esperaria que cada proprietário do serviço diagramase inicialmente suas próprias dependências imediatas - mas não dependências de dependências e assim por diante. E, como as informações já estão no código, eu não esperaria necessariamente que esses diagramas fossem mantidos daqui para frente.

^{Se você realmente deseja uma imagem global, verifique os scripts de configuração / construção. O que você faz com essa saída, como a armazena e assim por diante depende inteiramente de quais decisões os dados o ajudarão a tomar.}

Eu acho que uma boa idéia é criar um diagrama de integrações e incluí-lo no seu repositório. Escolha alguma ferramenta gratuita (como draw.io) que pode exportar o diagrama em um arquivo XML ou JSON e confirmar esse arquivo no seu repositório. Se você usa o Github ou o Gitlab, gere a imagem a partir deste diagrama e inclua no Wiki ou mesmo no arquivo README.md, para que a imagem fique visível sempre que o desenvolvedor visualizar o repositório a partir do navegador.

A mesma estratégia pode ser usada para o banco de dados.

Sobre a documentação dos recursos da API, o Swagger é uma boa opção.

Esse problema se amplifica quando você tem muitos serviços que são interdependentes entre si. Talvez nesse momento você esteja fazendo microsserviços errados, mas eu discordo.

Isso é um problema, com certeza.