ContacteGuia de disseny de Topics i Schemas
Navegació
| ⬅️ Ordre, Clau i Particionat | Patrones Event-Driven amb EventHub ➡️ |
|---|
Quan he de consultar aquesta guia?
Consulta aquesta guia:
- abans de crear nous topics o schemas,
- quan dissenyes un nou cas d’ús,
- quan necessites una visió global de bones pràctiques.
Aquesta guia no substitueix els estàndards obligatoris, sinó que ajuda a prendre bones decisions de disseny.
Obligatori vs recomanació i on tramitar: aquesta guia recull recomanacions de disseny. Quins estàndards són obligatoris i quins recomanats (naming, particionat, compatibilitat, retenció…) es defineix a Criteris i estàndards. Per sol·licitar recursos, feu servir la plantilla de sol·licitud amb el flux Excel + JIRA + GEH; abans de producció, seguiu les checklists de desplegament.
Guia de disseny de Topics i Schemas
El disseny correcte de topics i schemas és clau per garantir que les integracions amb EventHub siguin escalables, comprensibles i sostenibles en el temps.
Aquesta pàgina recull els criteris bàsics que han de seguir els equips abans de crear o evolucionar recursos a la plataforma.
Principis generals
En el disseny de topics i schemas cal prioritzar:
- claredat funcional
- desacoblament entre productors i consumidors
- estabilitat del contracte de dades
- escalabilitat
- evolució controlada
Cada topic i cada schema han de tenir:
- un cas d’ús clar
- un owner identificat
- una convenció de nom coherent
- un model d’evolució previst
Disseny de topics
Definir el propòsit del topic
Abans de crear un topic cal respondre:
- Quin esdeveniment representa?
- Quin domini funcional cobreix?
- Qui n’és l’owner?
- Qui el publicarà?
- Qui el consumirà?
No s’han de crear topics:
- genèrics
- exploratoris
- sense finalitat clara
- duplicats respecte a altres ja existents
Naming del topic
El nom del topic ha de seguir la convenció corporativa definida per la plataforma.
El nom ha de permetre identificar com a mínim:
- aplicació owner
- domini funcional
- tipus d’esdeveniment
Cal evitar:
- noms genèrics
- abreviatures no documentades
- versionat explícit en el nom del topic
- noms ambigüs o poc expressius
Exemple orientatiu:
<codi_aplicacio>-<domini>-<event>
Ownership
Tot topic ha de tenir un owner clarament definit.
L’owner:
- és responsable funcional del recurs
- és interlocutor amb l’Oficina EventHub
- és responsable de l’evolució del topic
- no ha de coincidir necessàriament amb productor ni consumidor
No es permeten topics sense ownership.
Particions
El nombre de particions s’ha de definir segons:
- volum esperat de missatges
- necessitat de paral·lelisme
- requisits d’ordre
- capacitat de consum
Cal recordar que Kafka només garanteix ordre dins d’una partició.
Per tant:
- si cal ordre per una entitat concreta, tots els esdeveniments d’aquesta entitat han d’anar amb la mateixa clau
- si no cal ordre global, es pot prioritzar paral·lelisme
Cal evitar:
- infra-dimensionament de particions
- sobre-particionat sense justificació
Clau del missatge
La clau determina la partició i condiciona l’ordre dels esdeveniments.
Cal documentar sempre:
- quin camp s’utilitza com a clau
- per què s’ha escollit aquest camp
- quin requisit funcional cobreix
Una clau mal escollida pot provocar:
- desordre funcional
- particions desequilibrades
- pèrdua de rendiment
Retenció
La retenció s’ha d’ajustar a:
- necessitat funcional real
- temps de resolució d’incidències
- volum esperat de dades
- impacte en emmagatzematge
Com a criteri general, s’ha d’evitar:
- retencions excessives
- retenció indefinida sense justificació
- configuracions no alineades amb el cas d’ús
Disseny de schemas
Utilitzar Schema Registry
Els esquemes dels esdeveniments s’han de gestionar de forma centralitzada a través de Schema Registry.
Això permet:
- govern del contracte de dades
- compatibilitat entre versions
- traçabilitat de l’evolució
- reducció de riscos de trencament
Dissenyar l’esquema com a contracte
Un schema no és només una estructura tècnica. És un contracte entre productor i consumidor.
Per tant, s’ha de dissenyar pensant en:
- estabilitat
- llegibilitat
- reutilització
- evolució futura
Cal evitar:
- camps sense significat clar
- estructures massa lligades a un sistema intern
- dependència de models temporals o locals
Compatibilitat
L’evolució dels schemas ha de mantenir compatibilitat amb els consumidors existents, sempre que el cas d’ús no justifiqui explícitament una ruptura controlada.
Abans d’introduir canvis cal analitzar:
- consumidors afectats
- impacte funcional
- necessitat de convivència entre versions
Canvis incompatibles poden provocar errors de consum o de serialització.
Versionat
El versionat dels schemas s’ha de fer de forma controlada.
Cal:
- registrar cada evolució
- documentar el canvi
- validar-lo en entorns previs
- comunicar-lo quan afecti consumidors
No s’ha de versionar en el nom del topic.
Bones pràctiques de disseny
- un topic ha de representar un flux clar i governat
- un schema ha de ser estable i comprensible
- el model d’esdeveniments ha d’estar orientat al domini funcional
- cal pensar en múltiples consumidors des del disseny
- cal documentar clau, retenció, particions i ownership
- cal planificar l’evolució des de la primera versió
Errors habituals a evitar
- crear topics sense cas d’ús real
- definir massa particions sense necessitat
- utilitzar claus inconsistents
- modelar esdeveniments massa tècnics o interns
- canviar schemas sense avaluar consumidors
- duplicar topics per manca de govern