Arquitectura de servidor REST amb Delphi per a empreses

Moltes empreses es troben avui davant d’una situació similar: una aplicació de negoci creixent (sovint Delphi/VCL) modela processos centrals, però de sobte ha de proveir nous canals. Un portal de clients necessita dades i tràmits, els usuaris mòbils esperen accessos segurs, i sistemes tercers (ERP, DMS, CRM, BI) requereixen integracions. En aquesta situació, una REST-API sembla el pas evident. En la pràctica, les iniciatives d’API rarament fallen per HTTP o JSON, sinó per una distribució poc clara de responsabilitats entre client, servidor i capa de dades.

Una arquitectura sòlida de REST-Server amb Delphi no neix posant «uns quants endpoints» sobre les taules existents. Neix quan l’empresa considera conjuntament regles funcionals, requisits de seguretat, sobirania de dades, límits de transacció i conceptes d’operació. El REST-Server esdevé així la capa contractual estable entre la lògica de negoci i els consumidors: client d’escriptori, portal, serveis, socis d’interfície. Precisament aquí Delphi desplega els seus punts forts: desenvolupament ràpid, execució robusta, codi nadiu performant, bona connexió a bases de dades (p. ex. mitjançant BDE-reemplaçament amb connexió nativa) i la possibilitat d’encapsular la lògica de negoci de manera controlada en biblioteques o mòduls de servidor.

Aquest article descriu com les empreses poden planificar REST-Server amb Delphi perquè es mantinguin coherents a nivell funcional, s’integrin en l’arquitectura existent i no es converteixin en font d’errors en explotació. El focus està en principis d’arquitectura, trampes típiques en projectes de modernització i components concrets per a seguretat, accés a dades, versionament i observabilitat.

Per què una REST-API a l’empresa és una decisió arquitectònica

En un món clàssic client‑servidor moltes regles estaven implícites al client d’escriptori: validacions, canvis d’estat, càlculs i fins i tot permisos. Mentre només existia un client això no era crític —més aviat una mala pràctica però manejable. Quan diversos consumidors accedeixen als mateixos objectes de negoci, el model falla:

• Un portal no pot «reutilitzar» les validacions del client.
• Les aplicacions mòbils han de ser offline‑capables, però no han de duplicar regles funcionals.
• Les integracions necessiten contractes estables i versionats i una semàntica d’errors clara.
• Compliance exigeix accessos traçables, models de rols i capacitat d’auditoria.

L’API es converteix en el punt on conflueixen lògica de negoci, drets i accés a dades. Per tant, la seva arquitectura decideix si el vostre sistema serà ampliable a llarg termini o simplement generarà noves deutes tècniques.

Delphi com a plataforma per a REST-Server: punts forts i casos d’ús típics

Delphi sovint s’associa a aplicacions d’escriptori. Per a REST-Server, però, també és molt adequat, especialment quan cal reaprofitar lògica existent o oferir serveis de gran rendiment. Casos d’ús típics en entorns B2B:

• Capa d’API per software existent: l’aplicació funcional existent en Delphi es manté com a UI, i el REST-Server encapsula l’accés a dades i regles per a nous consumidors.
• Backend per a portals/àrea de clients: el web‑portal utilitza endpoints REST que comparteixen el mateix nucli de regles que els processos interns.
• Servidor d’integracions i interfícies: connexió amb ERP/DMS/CRM, import/export, processament d’esdeveniments, tasques programades.
• Linux-Services o Windows Services: processos de llarga durada, workers de cues, schedulers, fluxos documentals.

El que importa no és tant l’etiqueta del framework sinó la disciplina en el disseny de capes, concurrència, maneig d’errors i desplegament. Delphi permet ambdues coses: iteracions ràpides i alhora una arquitectura neta i modular —si es planifica conscientment.

Model en capes: Layer-3 com a base per a APIs duradores

Per a software empresarial, ha demostrat la seva eficàcia un model de capes clar i lleuger. En l’entorn Delphi sovint es descriu com a Layer-3 Architektur. Els termes varien, però les responsabilitats han de ser inequívocament definides:

1) API-/Transport‑Layer (HTTP, serialització, routing)

Aquesta capa gestiona HTTP, autenticació a nivell de protocol, formats Request/Response, enrutament, codis d’estat, Content‑Type, compressió. No hi haurien d’entrar regles funcionals. Objectiu: intercanviabilitat i testabilitat. Si més endavant amplieu una REST-API cap a protocols addicionals (p. ex. WebSocket, patrons semblants a gRPC, Server‑Sent Events), el nucli funcional ha de romandre estable.

2) Domain-/Service‑Layer (lògica de negoci, casos d’ús, drets, transaccions)

Aquí resideix la veritat funcional: màquines d’estat, càlculs, plausibilitats, regles multi‑tenant, comprovacions de drets per a accions funcionals. Aquesta capa hauria de ser independent de la UI i, preferiblement, funcionar sense coneixement d’HTTP. L’ideal és implementar casos d’ús com «autoritzar comanda», «tancar ticket», «generar factura» en lloc d’operacions CRUD directes sobre taules.

3) Data‑Access‑Layer (repositoris, SQL, FireDAC, mapeig)

Aquesta capa encapsula la persistència: SQL, stored procedures, control de transaccions, estratègies de bloqueig, pool de connexions, peculiaritats específiques de BD. En Delphi BDE-Ablosung mit nativer Anbindung sovint és una elecció pragmàtica, especialment en migracions (reemplaçament de BDE) i en entorns amb bases diverses (SQL Server, PostgreSQL, MariaDB, Firebird). És important que el Data‑Access‑Layer no tingui coneixement d’HTTP ni prengui decisions de negoci.

Aquest model redueix l’acoblament: canvis en el model de dades no obliguen a reescriure l’API, i nous clients hereten automàticament la mateixa lògica. Especialment en la Delphi Modernisierung, és la base per desvincular gradualment aplicacions d’escriptori existents sense interrompre l’explotació.

Disseny d’API per a software empresarial: no només CRUD, sinó contractes funcionals

Moltes APIs comencen amb endpoints com /customers, /orders, /documents i implementen CRUD. Això pot ser suficient per eines internes, però en software empresarial resulta aviat massa superficial. Els processos funcionals estan formats per transicions d’estat, regles, efectes secundaris i permisos.

Modelar clarament recursos, accions i estats

Un patró millor és combinar recursos amb accions clares, p. ex.:

• Llegir recurs: GET /orders/{id}
• Disparar acció: POST /orders/{id}/release
• Generar document: POST /orders/{id}/documents/invoice
• Comprovar estat: GET /orders/{id}/status

Així queda explícit en el contracte de l’API que «autoritzar» no és simplement una actualització d’un camp. El servidor pot centralitzar validacions, permisos, transaccions, auditoria i processos secundaris.

Semàntica d’errors i validació: fer‑ho previsibl e pels clients

Els clients empresarials han de poder distingir errors: errors de validació (400), manca d’autorització (403), conflicte per canvi paral·lel (409), rebuig funcional (sovint 409 o 422), problemes temporals de backend (503). És important una estructura d’errors coherent, p. ex. amb codi d’error, missatge, indicacions opcionals per camps i una ID de correlació. Així un portal pot mostrar missatges comprensibles i suport/operacions poden rastrejar incidents eficientment.

Seguretat: autenticació no és el mateix que autorització

En contextos B2B la seguretat rarament falla per xifrat, sinó per falta de separació entre identitat, rols i permisos funcionals. Una arquitectura de REST-Server ha de distingir, per tant, dues capes:

Autenticació (qui és?)

Els mètodes habituals són enfocaments basats en tokens (p. ex. JWT o tokens opaques), combinats amb TLS i una estratègia clara de sessions. Decisiu és la durada del token, mecanisme de refresh, bloqueig en cas de canvi de rols i la necessitat de tenir proveïdors d’identitat diferents per a portals i sistemes interns. Els Delphi-Server poden actuar com a resource‑servers i, segons la configuració, també emetre tokens. En moltes arquitectures empresarials la integració amb sistemes d’identitat existents (p. ex. AD/LDAP, solucions SSO) és un punt central.

Autorització (té permís?)

L’autorització ha d’estar al Domain-/Service‑Layer. Rols i drets rarament són purament tècnics; depenen de tenant, ubicació, unitat organitzativa, estat contractual o fase de procés. Bones pràctiques:

• Model de rols (p. ex. Admin, Gestió, Auditor) com a base
• Polítiques funcionals («només pot generar factura en l’estat X», «només pot veure els seus propis tickets»)
• Multitenència com a estàndard: cada request necessita context de tenant
• Auditoria: qui va executar quina acció i quan

L’API no hauria de limitar‑se a retornar «accés permès/denegat», sinó impedir al servidor que paràmetres maliciosos facin visibles dades d’altres tenants. Això pot semblar obvi, però en sistemes heretats és una de les fallades arquitectòniques més freqüents quan es transformen taules en HTTP ràpidament.

Accés a dades amb FireDAC: transaccions, pooling i estratègia de base de dades

En aplicacions empresarials l’accés a dades és el factor d’estabilitat: pics de càrrega, deadlocks, informes llargs, actualitzacions paral·leles, imports massius. FireDAC és en l’ecosistema Delphi un component provat per donar accés unificat a diverses DB. Per a una arquitectura de REST-Server són especialment rellevants els punts següents:

Límits de transacció per cas d’ús

Una REST-API és típicament basada en requests. Això s’ajusta bé a «transacció per cas d’ús»: dins d’un request s’obre una transacció, s’executen operacions funcionals i després commit/rollback. Important: no posis automàticament cada endpoint dins d’una transacció, però sigues consistent en les operacions d’escriptura. Els endpoints de lectura també poden necessitar transaccions segons el nivell d’aïllament requerit per obtenir vistes consistents.

Estratègia de connexions i paral·lelisme

La paral·lelitat del servidor significa moltes peticions simultànies, cadascuna amb accés a BD. Planifiqueu, per tant:

• mides de pool limitades i monitoritzades
• timeouts per consultes i connexions
• regles clares per a operacions de llarga durada (externalitzar-les a jobs/workers)

Un error habitual és executar informes costosos o exportacions de masses de dades de forma síncrona sobre la mateixa instància d’API que serveix peticions interactives. Millor separar: interactivitat vs. batch/async.

Modernització de la base de dades com a part de la planificació d’API

Si en el llegat encara existeixen accés a dades antics (p. ex. BDE), l’API es converteix en catalitzador: obliga a definir límits clars d’accés a dades. Un reemplaçament controlat cap a FireDAC redueix riscos i incrementa portabilitat (PostgreSQL, MariaDB, SQL Server). Important: no plantegeu això com un «Big Bang», sinó de manera incremental: els casos d’ús nous del servidor empren el nou Data‑Access‑Layer, mentre les parts antigues s’adapten progressivament.

Versionament i compatibilitat cap enrere: els contractes d’API protegeixen

Les empreses sovint subestimen el cost dels breaking changes. Quan un portal de clients, un sistema partner o un Windows- und Linux-Services depèn de la vostra API, ja no es poden renombrar camps «a la ràpida». Per això una estratègia de versionament neta és obligatòria.

Regles pragmàtiques per al versionament

• No fer breaking changes sense versió: no renomear/eliminar camps, no reinterpretar endpoints.
• Ampliar en lloc de canviar: afegir camps nous i marcar els antics com deprecated.
• Defaults compatibles: evitar nous camps obligatoris o derivar‑los al servidor.
• Versionament explícit: p. ex. /v1/… o via header; més important que la tècnica és la coherència.

Per a equips Delphi això també significa: mantenir DTOs estables i dissenyar mappings amb intenció, en lloc de serialitzar objectes de domini 1:1. Al principi implica més treball, però redueix els costos de suport a llarg termini.

Observabilitat: logs, mètriques i traces des del primer moment

En explotació productiva «funciona en el meu entorn» no serveix si no es poden reproduir els errors. Precisament els REST-Server que servissan molts consumidors necessiten un mínim d’observabilitat:

Logging estructurat amb ID de correlació

Cada request hauria de portar una ID de correlació (acceptar‑la des del client o generar‑la) i apareixer en els logs. Les entrades de log han de ser estructurades (p. ex. JSON) per permetre l’ingest a sistemes centrals. Com a mínim cal:

• Mètode de request, ruta, codi d’estat, durada
• Context d’usuari/tenant (pseudonimitzat/complint normativa)
• Durada de BD i classe d’error
• ID de correlació per a suport

Mètriques per capacitat i tendències d’errors

Per escalar i garantir estabilitat necessiteu mètriques: requests per minut, lateses p95/p99, taxes d’error per endpoint, ocupació del pool de BD, longituds de cues. No cal un «cloud‑native overkill», però sense xifres les discussions de rendiment es converteixen en opinió.

Maneig d’errors i excepcions com a component arquitectònic

Les excepcions de Delphi no han de filtrar‑se descontroladament cap a l’exterior. Una middleware d’excepcions central (o un handler global) ha de traduir excepcions a respostes d’error coherents, amb ID de suport i codis HTTP útils. Els stacktraces han d’anar als logs segurs, no a les respostes als clients.

Síncron vs asíncron: treure els processos llargs de la resposta REST

Molts processos empresarials no són «request/response en 200 ms»: generació de PDF, import de dades, execució d’interfícies, reconciliacions, canvis massius, arxivament. Aquests workloads rarament pertanyen a un endpoint REST sincrònic, perquè ocupen threads, provoquen timeouts i bloquegen usuaris.

Patró de jobs

Una pràctica provada és: un endpoint inicia un job i el servidor retorna immediatament una Job‑ID. Un altre endpoint retorna l’estat/resultado. Opcionalment un callback/webhook pot notificar. En Delphi això es pot implementar amb serveis worker, una taula de jobs i una màquina d’estats clara. Avantatge: estabilitat i escalabilitat previsible.

Cues i serveis

Segons l’entorn, una message queue pot ser útil, però no és obligatòria. El principi és important: les APIs interactives han de romandre responsives; els processos batch han de córrer de manera controlada, repetible i observable —ja sigui com a Windows Services o Linux-Services segons el desplegament.

Desplegament a l’empresa: Windows, Linux, containers, On‑Prem

Una arquitectura de REST-Server només està «llesta» si és operable. Les empreses difereixen: servidors clàssics Windows, hosts virtualitzats Linux, plataformes de containers, zones de xarxa estrictes, proxies i requisits de certificats. Delphi és flexible en aquest sentit, sempre que les dependències es controlin netament.

Configuració i secrets

La configuració ha de ser dependent de l’entorn (Dev/Test/Prod). Les credencials no han d’estar a l’EXE ni al repositori. Utilitzeu emmagatzematge segur (p. ex. el secrets‑management de la plataforma) i separau valors de configuració dels llançaments de codi. Planifiqueu també rotacions (contrasenya BD, API‑Keys) sense haver de reconstruir el sistema.

Estrategies de llançament i rollback

Si diversos consumidors depenen d’una API, necessiteu llançaments controlats: scripts de migració de BD, feature toggles per activació gradual, i camins de rollback clars. Especialment els canvis en la base de dades han de ser retrocompatibles si es vol mantenir la possibilitat de rollback de la versió del servidor.

Integració amb software existent: modernització pas a pas en lloc de Big Bang

En moltes paisatges Delphi el nucli funcional és valuós però tècnicament «enganxat»: accessos a dades propers a la UI, estats globals i responsabilitats barrejades. Una REST-API pot ser risc i oportunitat. L’objectiu ha de ser un camí que aporti millores mesurables amb un esforç raonable.

Enfocament Strangler per a APIs

En lloc de refer-ho tot, definiu punts d’interfície funcionals que aportin benefici real: p. ex. «estat de comanda i documents per al portal de clients», «lookup de dades mestres per a usuaris mòbils», «interfície per a assentaments ERP». Aquests casos d’ús s’implementen com a noves funcions d’API, incloent Domain‑Layer i Data‑Access. El client antic pot migrar gradualment als mateixos casos d’ús del servidor sense necessitat de redissenyar la UI immediatament.

Lògica compartida: útil, però controlada

Delphi permet reutilitzar biblioteques funcionals tant al servidor com a les aplicacions existents. Pot ser un pont, però també té riscos: si les dependències de UI s’infiltren en la lògica compartida, es perd l’entropia. Una regla clara ajuda: comparteix només lògica sense UI, sense estats globals, amb interfícies clares i unitats testables. Tot el que no compleixi això es manté separat.

Errors típics en projectes de REST-Server — i com evitar‑los

«Publicarem simplement taules»

Si els endpoints reflecteixen directament taules es crea un sistema inestable: qualsevol refactorització de BD es converteix en un breaking change de l’API, la lògica funcional es duplica als clients i són més probables vulnerabilitats per paràmetres no verificats. Millor: casos d’ús de domini i DTOs que estabilitzin el contracte.

Permisos funcionals només al client

Els clients són intercanviables i manipulables. L’autorització ha d’estar al servidor i ha de considerar regles funcionals, no només rols tècnics.

Absència d’estratègia clara per a concurrència

Les actualitzacions paral·leles passen: dos gestors, portal i client intern, o un job d’import. Sense optimistic locking (p. ex. RowVersion/Timestamp), codis de conflicte (409) i regles de merge clares, apareixen pèrdues de dades o l’error de «últim escriu guanya».

Processos llargs bloquegen endpoints interactius

La generació síncrona de PDFs o exportacions provoca timeouts i una experiència d’«enganxament». Millor aplicar el patró de job amb endpoints d’estat.

Observabilitat enganxada a posteriori

Sense ID de correlació, logs estructurats i mètriques, cada incidència es converteix en una recerca. La possibilitat d’observar no és un luxe, és un requisit d’operació.

Checklist concreta per la vostra arquitectura de REST-Server amb Delphi

• Separar clarament capes: Transport (HTTP), Domini (Use Cases), Data Access (FireDAC/SQL).
• Entendre l’API com a contracte: mantenir DTOs estables, planificar versionament, evitar breaking changes.
• Seguretat en dues capes: autenticació (tokens) més autorització (polítiques funcionals, multitenència).
• Posar transaccions de manera conscient: per cas d’ús, timeouts, estratègia de conflictes.
• Fer asíncrons els processos llargs: jobs/workers, Windows o Linux-Services.
• Integrar observabilitat: ID de correlació, logs estructurats, mètriques, maneig d’errors central.
• Planificar desplegament realista: configuració/secrets, rollback, migracions de BD.
• Modernització iterativa: casos d’ús de valor primer, desacoblament progressiu de parts antigues.

Conclusió: els REST-Server aporten valor quan són arquitectura d’explotació i de negoci

Una arquitectura de REST-Server amb Delphi és especialment eficaç quan no es veu com una «coberta tècnica», sinó com el nucli connector entre processos, dades i canals. El decisiu són capes netes (Layer-3 Architektur), endpoints modelats funcionalment, lògica de seguretat i multitenència coherent, i un model d’explotació amb versionament, monitoratge i concurrència controlada. Així l’API esdevé una plataforma estable per portals, integracions, serveis i la modernització gradual de Delphi Modernisierung —sense posar en risc la substància funcional d’un sistema madur.

Si voleu examinar com desplegar una REST-API robusta sobre la vostra paisatge Delphi existent (incloent l’estratègia de BD, FireDAC, serveis i explotació), podeu contactar‑nos aquí: https://net-base-software-gmbh.de/kontakt/