Apéndice H — Migración de legacy backend (referencia)

Objetivo del apéndice

Cómo pasar del legacy :code:`index.ts` a la New Backend System, con el mapeo uno-a-uno de patrones comunes.

Diferencias clave

Concepto Legacy New Backend System

Punto de entrada

:code:`createPlugin()` + router manual

:code:`createBackendPlugin()` o :code:`createBackendModule()`

Router

:code:`app.use('/api/foo', router)`

:code:`httpRouter.use(await createRouter(…​))`

Config

:code:`Config.getOptionalString(…​)` con lectura directa

:code:`ConfigService` inyectado

Identity

Request headers ad-hoc

:code:`HttpAuthService.credentials()`

DB

:code:`Knex(…​)` instanciado a mano

:code:`DatabaseService` con migraciones

Logging

:code:`winston` o consola

:code:`LoggerService` (pino)

Paso 1 — Reescribir index.ts

// Antes (legacy)
const backend = new Backend({ ... });
backend.add(...);
// muchas líneas de routers
backend.start();

// Después (New Backend System)
const backend = createBackend();
backend.add(import('@backstage/plugin-catalog-backend'));
backend.add(import('@sazon/plugin-sazon-status-backend'));
backend.start();

Paso 2 — Convertir plugins

// Antes (legacy)
export default async function createPlugin({ ... }: PluginEnvironment) {
  const router = Router();
  router.get('/foo', ...);
  return router;
}

// Después (New Backend System)
export const fooPlugin = createBackendPlugin({
  id: 'foo',
  register(env) {
    env.registerInit({
      deps: { httpRouter: coreServices.httpRouter },
      async init({ httpRouter }) {
        httpRouter.use(await createRouter({ ... }));
      },
    });
  },
});

Paso 3 — Servicios

Pasa de singletons globales a deps declarativos:

env.registerInit({
  deps: {
    database: coreServices.database,
    logger: coreServices.logger,
    httpAuth: coreServices.httpAuth,
  },
  async init({ database, logger, httpAuth }) { ... },
});

Paso 4 — Custom services

Si tenías un service factory custom, decláralo con :code:`createServiceFactory`:

export const myCustomService = createServiceFactory({
  service: createServiceRef<MyService>({ id: 'my-custom', scope: 'plugin' }),
  factory: async () => MyServiceImpl,
});

Y lo registras con :code:`backend.add(myCustomService)`.

Compatibilidad

  • La legacy backend system sigue operativa en Backstage 1.x.

  • No puedes mezclar: si arrancas con :code:`createBackend(), todos los plugins deben ser NBS o estar envueltos en un :code:`legacyPlugin() shim.

  • Planifica la migración antes de que tu :code:`index.ts` legacy supere 500 líneas.

Para más