# Enrutamiento y enmascaramiento de URL ## Parámetros que reconoce el controlador El controlador lee sus parámetros de `@http_context/request/get`, es decir, de la cadena de consulta o de los marcadores de `routes.map`. | Parámetro | Requerido | Descripción | |---|---|---| | `_entities_type` | Sí | Tipo de entidad. Es la carpeta de la entidad y, salvo que el modelo fije `@table_name`, el nombre de la tabla | | `_entity_id` | No | Identificador de la entidad. Su presencia o ausencia decide la operación | | `_key` | No | Campo que se usa como identificador; si no se indica, `sys_pk` | | `_app_group` | No | Aplicación del administrador de conexiones (si no se fijó `@crudl.qname`) | | `_connection` | No | Conexión dentro de esa aplicación | | `ws` | No | Espacio de trabajo; con sesión, activa la suplantación de identidad | Hay otros parámetros para la redirección (`_redirect`, `_from_url_e`); vea [Patrón PRG](/es/devkron/2.0/marcos/crudl/prg-y-redireccion.md). ## Mapeo hacia el punto de entrada Los parámetros se pueden pasar en la URL, pero lo normal es dar URL limpias con una regla de `routes.map` en la carpeta protegida del sitio: ```text /tienda/{_entities_type}/{_entity_id?} > tienda/entry-point.dkl ``` | Sin regla | Con la regla | |---|---| | `/tienda/entry-point.dkl?_entities_type=cliente&_entity_id=10` | `/tienda/cliente/10` | La sintaxis completa de `routes.map` está en [Enrutamiento](/es/devkron/2.0/marcos/servidor-web/enrutamiento.md). Recuerde que el enrutamiento no distingue mayúsculas: un identificador que llega por la ruta (`/tienda/cliente/CLI-0001?_key=codigo`) llega en minúsculas (`cli-0001`). Con MySQL y su intercalación predeterminada la búsqueda funciona igual; en motores que distinguen mayúsculas, pase esos identificadores en la cadena de consulta. **No llame directamente al punto de entrada sin `_entities_type`.** Comprobado en 2.0: `GET /tienda/entry-point.dkl?_entities_type=pais` funciona, pero si la regla de `routes.map` captura `entry-point.dkl` como si fuera el tipo de entidad (por ejemplo, `GET /tienda/entry-point.dkl` con la regla de arriba), el marco intenta consultar la tabla `entry-point.dkl` y responde un error de SQL. ## Enmascaramiento de URL Para dar URL más descriptivas, la ruta lógica se puede armar con varios parámetros y asignar a una entidad. Por ejemplo, en lugar de `/tienda/cliente/` y `/tienda/factura/`: ```text /catalogos/ventas/clientes/ /catalogos/ventas/facturas/ ``` ### Cómo funciona 1. `routes.map` descompone la URL en parámetros con los nombres que usted elija. 2. `crudl.routes.pattern` declara **qué parámetros, y en qué orden**, forman la ruta lógica. 3. `crudl.routes.entity` compara la ruta lógica con un valor y, si coincide, asigna `_entities_type`. Lo que suele confundir: los segmentos de `crudl.routes.pattern` **no son segmentos de la URL, son nombres de parámetros**, y deben coincidir con los de `routes.map`. ### Funciones | Función | Qué hace | |---|---| | `crudl.routes.pattern("/p1/p2/p3")` | Declara un patrón. Al resolver, lee en orden el valor de cada parámetro y los une con `/`; si uno está vacío, se detiene ahí. Las diagonales inicial y final son opcionales | | `crudl.routes.entity(ruta, entidad)` | Si la ruta lógica es `ruta`, asigna `entidad` a `_entities_type` y devuelve `1`; si no, devuelve `0`. No distingue mayúsculas | | `crudl.route(ruta)` | Igual, pero sin cambiar `_entities_type`: para ejecutar lógica según la ruta | Registre un solo patrón por punto de entrada; para estructuras de URL distintas use puntos de entrada distintos. ### Ejemplo con código **`_protected/routes.map`** ```text /catalogos/{modulo}/{proceso}/{_entity_id?} > tienda/entry-point.dkl ``` **En `entry-point.dkl`**, antes de incluir el controlador: ```dkl do crudl.routes.pattern("/modulo/proceso") do crudl.routes.entity("ventas/clientes", "cliente") do crudl.routes.entity("ventas/facturas", "factura") ``` `GET /catalogos/ventas/clientes/1` produce `modulo=ventas`, `proceso=clientes` y `_entity_id=1`; el patrón arma `ventas/clientes`, coincide con la primera regla y asigna `_entities_type=cliente`. `catalogos` es parte de la URL pero no un parámetro, y `_entity_id` no forma parte de la ruta lógica. ### Definición declarativa con routes.json En lugar de escribir las llamadas, declare los patrones en `routes.json` dentro de `@path_root` + `@base_path` (aquí, `web/misitio.localhost/tienda/entidades/routes.json`). `crudl.loadRoutesJSON()` lo lee y hace las llamadas por usted: ```json [ { "pattern": "/modulo/proceso", "routes": [ { "route": "ventas/clientes", "entity_type": "cliente" }, { "route": "ventas/facturas", "entity_type": "factura" } ] } ] ``` Resultados reales con 2.0: ```text GET /catalogos/ventas/clientes/1 → {"sys_pk":1,...,"codigo":"CLI-0001",...} GET /catalogos/ventas/facturas/ → [] GET /catalogos/ventas/otros/ → 500, error de SQL ``` La última muestra el cuidado necesario: una ruta que no está en el archivo no asigna entidad, y el controlador intenta trabajar con un `_entities_type` vacío. Para que una ruta desconocida responda 404, valide después de cargar las rutas y termine el punto de entrada antes de incluir el controlador (un `rise_error` aquí no lo atiende el controlador de CRUD-L y produciría la página 500 del servidor): ```dkl do crudl.loadRoutesJSON() if @@(@http_context,"$request/get/_entities_type") == "" { @http_context<"response/http_status">: 404 @http_context<"response/headers/content-type">: "application/json;charset=utf-8" @http_context<"response/output">: "text" @http_context<"response/text">: '{"message":"Ruta no definida"}' return } ``` ```text GET /catalogos/ventas/otros/ → 404 Not Found, {"message":"Ruta no definida"} ``` Los elementos con `pattern`, `route` o `entity_type` vacíos se omiten. Si el archivo no existe, la función no hace nada. Para otro nombre de archivo, cambie `@crudl_routes_json` antes de llamarla: ```dkl @crudl_routes_json = "rutas-inventarios.json" do crudl.loadRoutesJSON() ``` ## Errores típicos | Síntoma | Causa y solución | |---|---| | `You have an error in your SQL syntax ... near 'where ifnull(sys_deleted,0)=0'` | `_entities_type` quedó vacío o con un valor que no es tabla (ruta no definida en `routes.json`). Valide como se muestra arriba | | El patrón nunca coincide | Los nombres de `crudl.routes.pattern` no son los de los marcadores de `routes.map` | | `routes.json` no se carga | No está en `@path_root` + `@base_path`, o `crudl.loadRoutesJSON()` se llamó antes de fijar esas variables |