Nombre completo de YAMLYAML Ain't Markup Language(un acrónimo recursivo), es un formato de serialización de datos legible por humanos.
YAML se usa a menudo en archivos de configuración, intercambio de datos y en diversos escenarios que requieren almacenar datos de forma estructurada.
La sintaxis de YAML es similar a la de otros lenguajes de alto nivel; puede expresar fácilmente listas, tablas hash, escalares y otras formas de datos.
Utiliza espacios en blanco para la indentación y depende en gran medida de la apariencia; es especialmente adecuado para expresar o editar estructuras de datos, diversos archivos de configuración, volcados de depuración y esquemas de archivos.
La extensión de los archivos de configuración de YAML es.ymlcomo:ejemplo.yml 。
Características y ventajas de YAML
El objetivo de diseño de YAML es una alta legibilidad, sintaxis concisa, cercana a los hábitos de escritura del lenguaje natural, y casi sin necesidad de símbolos adicionales.
En comparación con XML y JSON, YAML reduce en gran medida los corchetes y las comillas, lo que facilita la escritura.
Admite estructuras de datos complejas; puede expresar listas, diccionarios, estructuras anidadas e incluso admite características avanzadas como referencias y anclas.
Casi todos los lenguajes de programación principales tienen bibliotecas para analizar YAML, y el ecosistema de lenguajes es muy maduro.
Comparación de YAML con JSON y XML
Los tres formatos tienen sus propios enfoques; la siguiente tabla los compara desde varias dimensiones:
| Característica | YAML | JSON | XML |
|---|---|---|---|
| Legibilidad | Alto | Medio | bajo |
| Soporte de comentarios | Sí | No | Sí |
| Complejidad sintáctica | bajo | Medio | Alto |
| Usos comunes | Archivos de configuración | Intercambio de datos / API | Documentos / intercambio de datos |
Casos de uso comunes de YAML
YAML está en casi todas partes en la pila de desarrollo moderna; a continuación se presentan los casos más comunes:
Archivos de configuración de aplicaciones, como los de Spring Bootapplication.yml。
Herramientas de orquestación de contenedores, como los archivos de descripción de despliegue de Docker Compose y Kubernetes.
Configuración de pipelines de CI/CD, como las definiciones de flujos de trabajo de GitHub Actions, GitLab CI y CircleCI.
Front Matter de generadores de sitios estáticos, como los metadatos de páginas de Jekyll y Hugo.
Reglas básicas de sintaxis
Domina las reglas de escritura más básicas de YAML, incluyendo la indentación, los comentarios, la estructura de archivos, etc.
Reglas de indentación
YAML usaespaciospara la sangría y representar la jerarquía,no se puede usar la tecla Tab。
Los elementos del mismo nivel deben mantener la misma cantidad de indentación; generalmente se recomienda usar 2 espacios como unidad de indentación.
person: name: 张三 age: 25
Sintaxis básica
Las siguientes son las reglas de sintaxis más esenciales de YAML que debes recordar:
- Sensible a mayúsculas y minúsculas
- Usar la indentación para representar la jerarquía
- No se permite usar tabulaciones para la sangría, solo espacios
- La cantidad de espacios de sangría no es importante; basta con que los elementos del mismo nivel estén alineados a la izquierda.
- #Indica un comentario
- :Después del símbolo se debe añadir un espacio.
Sensible a mayúsculas y minúsculas
Los nombres de las claves, las cadenas, etc. en YAML distinguen entre mayúsculas y minúsculas.
NameynameSe considerarán dos claves diferentes; al escribir, se debe prestar atención a la consistencia.
Escritura de comentarios
Usa#El contenido que comienza con ese símbolo es un comentario; el comentario puede ocupar una línea propia o escribirse después del contenido.
# 这是一行注释 name: 张三 # 这也是注释
Extensión de archivo
Los archivos YAML suelen usar.yamlo.ymlcomo extensión; no hay diferencia esencial entre ambos, depende de los hábitos del proyecto.
Separador de documentos
---Se utiliza para marcar el inicio de un nuevo documento; es especialmente importante en archivos con múltiples documentos.
...Se utiliza para marcar el final de un documento; es una marca opcional.
--- doc: 第一个文档 --- doc: 第二个文档
Tipos de datos básicos
YAML admite tipos de datos básicos como cadenas, números, booleanos y nulos; cada tipo tiene su forma específica de escritura.
Resumen de tipos de datos
YAML admite los siguientes tipos de datos:
- Objeto: un conjunto de pares clave-valor, también llamado mapeo (mapping), hash (hashes) o diccionario (dictionary).
- Arreglo: un conjunto de valores ordenados, también llamado secuencia (sequence) o lista (list).
- Escalares (scalars): un valor único e indivisible.
Escalar (Scalar)
El escalar es la unidad de datos más básica en YAML y se divide en los siguientes tipos:
Cadena
Las cadenas pueden escribirse sin comillas o encerrarse entre comillas dobles o simples.
Las comillas dobles admiten caracteres de escape (como\n), las comillas simples no admiten escapes.
name: 张三 # 不加引号 name: "张三" # 双引号，支持转义字符 name: '张三' # 单引号，不支持转义
Número
YAML reconoce automáticamente enteros y números de punto flotante, sin necesidad de declarar el tipo adicionalmente.
age: 25 # 整数 price: 19.99 # 浮点数
Valor booleano
Los valores booleanos usantrueyfalsepara representarse.
is_active: true is_deleted: false
Valor nulo
El valor nulo se puede representar connull、~o simplemente no escribiendo nada.
value: null value: ~ value: # 什么都不写也表示 null
Ejemplo completo de escalares
El siguiente ejemplo muestra cómo se usan todos los tipos escalares, incluidos booleanos, números de punto flotante, enteros, valores nulos, cadenas, fechas y horas:
boolean:
- TRUE # true,True 都可以
- FALSE # false,False 都可以
float:
- 3.14
- 6.8523015e+5 # 可以使用科学计数法
int:
- 123
- 0b1010_0111_0100_1010_1110 # 二进制表示
null:
nodeName: 'node'
parent: ~ # 使用 ~ 表示 null
string:
- 哈哈
- 'Hello world' # 可以使用双引号或者单引号包裹特殊字符
- newline
newline2 # 字符串可以拆成多行，每一行会被转化成一个空格
date:
- 2018-02-17 # 日期必须使用 ISO 8601 格式，即 yyyy-MM-dd
datetime:
- 2018-02-17T15:02:31+08:00 # 时间使用 ISO 8601 格式，时间和日期之间使用 T 连接，最后使用 + 代表时区
Las fechas y horas deben usar el formato ISO 8601. El formato de fecha esyyyy-MM-dd, el formato de hora esyyyy-MM-ddTHH:mm:ss+zona horaria, en el medio se usaTpara conectarlos.
Cadenas multilínea
YAML ofrece dos formas de escribir cadenas multilínea, cada una adecuada para diferentes escenarios.
Estilo plegado (>)
Usa>el símbolo pliega el texto de varias líneas en una sola línea; los saltos de línea se reemplazan por espacios.
description: > 这是第一行 这是第二行 这是第三行
La escritura anterior equivale a:"Esta es la primera línea, esta es la segunda línea, esta es la tercera línea\n"
Estilo de conservación de saltos de línea (|)
El símbolo conserva los saltos de línea originales; es adecuado para escribir texto de varias líneas (como contenido de scripts).|Comparación entre | y >
script: | echo "第一行" echo "第二行" echo "第三行"
A continuación, usando el mismo contenido
se comparan las diferencias entre las dos formas de escritura:Foo\nBarConvertido a código JavaScript, es el siguiente:
this: | Foo Bar that: > Foo Bar
Se puede ver que,
{ this: 'Foo\nBar\n', that: 'Foo Bar\n' }
conserva los saltos de línea; el resultado es|; mientras queFoo\nBar\npliega los saltos de línea en espacios; el resultado es>ElegirFoo Bar\n。
o>depende de tus necesidades:|Si necesitas combinar el contenido de varias líneas en un solo párrafo, usa>; si necesitas conservar el formato original de saltos de línea (como scripts, poemas), usa|。
Estructuras de datos compuestas
YAML admite dos estructuras compuestas: mapeos y secuencias; ambas pueden anidarse libremente para expresar relaciones de datos arbitrariamente complejas.
Mapeo (Mapping / Diccionario)
Un mapa es una colección de pares clave-valor y es la estructura de datos más utilizada en YAML.
Sintaxis básica de pares clave-valor
name: 张三 age: 25 city: 北京
Mapas anidados
Mediante la sangría se puede anidar otro mapa dentro de un mapa, formando una estructura jerárquica.
person:
name: 张三
address:
city: 北京
zipcode: "100000"
Sintaxis de mapas en flujo
También se puede usarkey:{key1: value1, key2: value2, ...}la sintaxis de flujo.
key: {child-key: value, child-key2: value2}
Clave compleja (Complex Key)
Se utiliza un signo de interrogación seguido de un espacio para representar una clave compleja, junto con dos puntos y un espacio para representar un valor:
?
- complexkey1
- complexkey2
:
- complexvalue1
- complexvalue2
Significa que la propiedad del objeto es un array[complexkey1, complexkey2]y el valor correspondiente también es un array[complexvalue1, complexvalue2]。
Secuencia (Sequence / Lista)
Las secuencias utilizan-el prefijo para representar colecciones de datos ordenadas.
Sintaxis básica de listas
fruits: - 苹果 - 香蕉 - 橙子
Listas anidadas
matrix: - [1, 2, 3] - [4, 5, 6] - [7, 8, 9]
Arrays multidimensionales
YAML admite arrays multidimensionales y se pueden representar en línea:
key: [value1, value2, ...]
Si un submiembro de la estructura de datos es un array, se puede sangrar un espacio debajo de ese elemento:
- - A - B - C
Ejemplo complejo de array cuyos elementos son objetos
Un escenario práctico común: cada elemento del array es un objeto compuesto por múltiples propiedades:
companies:
-
id: 1
name: company1
price: 200W
-
id: 2
name: company2
price: 500W
Significa quecompaniesla propiedad es un array, y cada elemento del array a su vez está compuesto porid、name、pricetres propiedades.
Los arrays también se pueden representar en formato de flujo:
companies: [{id: 1,name: company1,price: 200W},{id: 2,name: company2,price: 500W}]
Uso combinado de mapeos y secuencias
Los mapas y las secuencias se pueden combinar de forma flexible para expresar estructuras de datos complejas.
students:
- name: 张三
age: 20
subjects:
- 数学
- 英语
- name: 李四
age: 22
subjects:
- 物理
- 化学
En el ejemplo anterior,studentses una secuencia, cada elemento es un mapa, y dentro del mapasubjectsa su vez es una secuencia. Esta combinación anidada es el núcleo de la expresividad de YAML.
Ejemplo de estructura compuesta
Los arrays y los objetos pueden formar estructuras compuestas. A continuación se muestra un ejemplo que incluye tanto listas como mapas:
languages: - Ruby - Perl - Python websites: YAML: yaml.org Ruby: ruby-lang.org Python: python.org Perl: use.perl.org
Al convertirlo a JSON, queda:
{
languages: [ 'Ruby', 'Perl', 'Python'],
websites: {
YAML: 'yaml.org',
Ruby: 'ruby-lang.org',
Python: 'python.org',
Perl: 'use.perl.org'
}
}
Sintaxis de flujo (Flow)
Además de la notación en bloques, YAML admite una sintaxis de flujo similar a JSON, adecuada para escenarios compactos.
Mapeo en flujo
Se utilizan llaves{}para envolver los pares clave-valor, separados por comas.
person: {name: 张三, age: 25, city: 北京}
Lista en flujo
Se utilizan corchetes[]para envolver los elementos, separados por comas.
fruits: [苹果, 香蕉, 橙子]
Comparación entre flujo y bloque, y casos de uso
| Estilo | Características | Casos de uso |
|---|---|---|
| Bloques (Block) | Mejor legibilidad y jerarquía clara | Datos con estructura compleja y niveles profundos |
| Flujo (Flow) | Más compacto, se expresa en una sola línea | Datos simples o pequeños datos incrustados en estructuras de bloques |
Ambos estilos también se pueden mezclar:
users:
- {name: 张三, age: 25}
- {name: 李四, age: 30}
Características avanzadas
YAML ofrece características avanzadas, como anclas, referencias y claves de fusión, para ayudar a reducir contenido repetido.
Anclas y referencias
Se utiliza¶ definir un ancla, y se usa*para referenciar el ancla, lo que permite evitar repetir el mismo contenido.
default_settings: &defaults adapter: postgres host: localhost development: <<: *defaults database: dev_db test: <<: *defaults database: test_db
En el ejemplo anterior,&defaultsdefine un ancla,*defaultsreferencia el contenido de ese ancla,<<e indica la fusión en los datos actuales.
La configuración anterior, al expandirse, equivale a:
defaults: adapter: postgres host: localhost development: database: myapp_development adapter: postgres host: localhost test: database: myapp_test adapter: postgres host: localhost
Referencias a anclas en listas
Las anclas también se pueden usar en listas:
- &showell Steve - Clark - Brian - Oren - *showell
Al convertirlo en un array de JavaScript, queda:
[ 'Steve', 'Clark', 'Brian', 'Oren', 'Steve' ]
Claves de fusión
<<Se utilizan para fusionar el contenido de un mapa en el mapa actual, normalmente en combinación con anclas.
Claves de fusión<<Es una característica de la especificación YAML 1.1 y está soportada por la mayoría de los analizadores de YAML. Permite que los archivos de configuración sean más concisos, pero hay que tener en cuenta que no forma parte de la especificación JSON; al convertir a JSON se expande al contenido real.
Soporte para múltiples documentos
En un archivo YAML se pueden---almacenar varios documentos independientes separados entre sí, algo habitual en los archivos de configuración de Kubernetes.
--- kind: Pod metadata: name: pod-1 --- kind: Pod metadata: name: pod-2
Etiquetas y conversión de tipos
YAML permite especificar explícitamente el tipo de dato mediante etiquetas (Tag), utilizando!!el prefijo para declararlo.
explicit_string: !!str 123 explicit_int: !!int "123" explicit_float: !!float "3.14"
Las etiquetas más comunes incluyen!!str(cadena de texto),!!int(entero),!!float(número de coma flotante),!!bool(booleano),!!null(nulo), entre otras.
Errores comunes y precauciones
YAML es muy sensible al formato. A continuación se presentan los tipos de errores más comunes y cómo evitarlos.
Errores de análisis por indentación incorrecta
YAML es extremadamente sensible a la sangría: la cantidad de sangría en un mismo nivel debe ser exactamente igual; de lo contrario, se producirá un error de análisis.
# 错误示例：缩进不一致 person: name: 张三 age: 25 # 缩进多了一个空格，会报错
Problema de mezclar tabulaciones y espacios
La especificación de YAML establece claramenteque no se permite usar tabulaciones para la sangríay que se deben usar espacios de manera uniforme; de lo contrario, la mayoría de los analizadores mostrarán un error.
Se recomienda activar en el editor la opción «convertir tabulaciones en espacios» para evitar mezclar caracteres de tabulación accidentalmente. La mayoría de los editores modernos admiten.yamly.ymlactivar automáticamente esta opción para los archivos YAML.
Problema de escape de caracteres especiales
Cuando una cadena contiene:、#、{、}、[、]caracteres especiales como estos, se recomienda envolver la cadena entre comillas para evitar que el analizador la malinterprete.
title: "标题: 副标题" # 冒号需要用引号包裹 tag: "#重要" # 井号需要用引号包裹，否则会被当作注释
Casos en los que las cadenas necesitan comillas
En los siguientes casos se recomienda añadir comillas explícitamente para evitar que el analizador de YAML haga una inferencia de tipo incorrecta:
| Escenario | Ejemplo | Descripción |
|---|---|---|
| Cadena que comienza con un número | "100000" | Sin comillas se analizará como un número |
| Palabras booleanas ambiguas | "true"、"false"、"yes"、"no" | Sin comillas se analizará como un valor booleano |
| Palabras de valor nulo | "null"、"~" | Sin comillas se analizará como null |
| Contiene símbolos especiales | "Título: Subtítulo" | Los dos puntos, la almohadilla, etc., pueden malinterpretarse como marcadores de sintaxis |
Aplicación práctica
Comprender el uso de YAML en proyectos reales mediante ejemplos completos en escenarios prácticos.
Escribir un archivo de configuración simple
A continuación se muestra un archivo de configuración típico de una aplicación que ilustra la estructura habitual de YAML en proyectos reales:
# 应用基本配置 app: name: MyApplication version: 1.0.0 debug: false # 数据库连接配置 database: host: localhost port: 5432 username: admin password: "secret" # 日志配置 logging: level: info file: /var/log/app.log
Uso de YAML en Docker Compose
Docker Compose utiliza YAML para definir la orquestación de servicios de aplicaciones con múltiples contenedores:
version: "3"
services:
web:
image: nginx:latest
ports:
- "80:80"
db:
image: mysql:8.0
environment:
MYSQL_ROOT_PASSWORD: example
Uso de YAML en Kubernetes
Kubernetes utiliza YAML para definir distintos objetos de recurso. A continuación se muestra un ejemplo de definición de un Pod:
apiVersion: v1
kind: Pod
metadata:
name: nginx-pod
spec:
containers:
- name: nginx
image: nginx:latest
ports:
- containerPort: 80
Uso de YAML en GitHub Actions
GitHub Actions utiliza YAML para definir flujos de trabajo de CI/CD:
name: CI
on: [push, pull_request]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Run tests
run: npm test
Herramientas y validación
Se recomiendan algunas herramientas y recursos útiles de YAML para ayudarte a escribir y validar archivos YAML de manera más eficiente.
Herramientas en línea de validación de YAML
YAML Lint es la herramienta de validación en línea más utilizada. Puedes buscar "yamllint online" para encontrar sitios web de validación disponibles.
Varios IDE también incluyen funciones integradas de comprobación de sintaxis de YAML, que pueden mostrar errores en tiempo real mientras se escribe.
Bibliotecas para analizar YAML en lenguajes de programación comunes
| Lenguaje | Biblioteca habitual | Características |
|---|---|---|
| Python | PyYAML、ruamel.yaml | PyYAML es la más popular; ruamel.yaml es compatible con YAML 1.2 |
| JavaScript / Node.js | js-yaml | Funciona en navegadores y en entornos Node.js |
| Java | SnakeYAML | Biblioteca de análisis de YAML utilizada por defecto en Spring Boot |
| Go | gopkg.in/yaml.v3 | La biblioteca de YAML más utilizada en el ecosistema Go |
| Ruby | Psych | Incluida en la biblioteca estándar, no requiere instalación adicional |
Plugins recomendados para editores
| Editor | Plugin recomendado | Funciones |
|---|---|---|
| VSCode | Plugin YAML de Red Hat | Resaltado de sintaxis, validación de formato y validación de esquema |
| IntelliJ IDEA / PyCharm | Soporte integrado | No requiere instalación adicional, listo para usar |
| Sublime Text | Plugins relacionados con YAML | Mejoran el resaltado de sintaxis y las funciones de formato |