133 lines
5.5 KiB
Markdown
133 lines
5.5 KiB
Markdown
# Анализ ширины колонок таблиц документации
|
||
|
||
> Методика определения оптимальных ширин колонок на основе реальных данных из YAML-спек.
|
||
|
||
---
|
||
|
||
## Методика
|
||
|
||
### Источник данных
|
||
|
||
Все параметры ресурсов генерируются из YAML-спек в `generated/<stand>/resources_yaml/*.yaml`.
|
||
Скрипт анализа собирает ВСЕ параметры из всех YAML-файлов (только операции `create` и `modify`, включая вложенные `sub_params`).
|
||
|
||
### Что измеряется
|
||
|
||
Для каждого параметра извлекаются 5 групп значений:
|
||
|
||
| Группа | Поля YAML | Назначение в таблице |
|
||
|---|---|---|
|
||
| Code | `code` | Название параметра |
|
||
| Type | `data_type`, `type` | Тип данных |
|
||
| Default | `default` | Значение по умолчанию |
|
||
| Description | `descr`, `man` | Описание |
|
||
| Constraints | `min_value`, `max_value`, `regex`, `value_list`, `max_length`, `min_length`, `func`, `ref_svc_id`, `unique` | Ограничения |
|
||
|
||
Для каждой группы вычисляется:
|
||
- MAX длина строки (символов)
|
||
- AVERAGE длина
|
||
- % значений длиннее 30/50/100/200/500 символов
|
||
|
||
### Код анализа
|
||
|
||
```python
|
||
import os, yaml
|
||
|
||
YAML_DIR = 'generated/test/resources_yaml'
|
||
all_params = []
|
||
nested_count = 0
|
||
|
||
def extract_params(svc, op, params_list, depth=0):
|
||
global nested_count
|
||
for p in params_list:
|
||
if not isinstance(p, dict): continue
|
||
all_params.append((svc, op, p, depth))
|
||
sub = p.get('sub_params', [])
|
||
if sub:
|
||
nested_count += len(sub)
|
||
extract_params(svc, op, sub, depth + 1)
|
||
|
||
for fname in sorted(os.listdir(YAML_DIR)):
|
||
if not fname.endswith('.yaml'): continue
|
||
with open(os.path.join(YAML_DIR, fname)) as f:
|
||
data = yaml.safe_load(f)
|
||
svc = data.get('name', fname)
|
||
for op in data.get('operations', []):
|
||
if op.get('action') not in ('create', 'modify'): continue
|
||
extract_params(svc, op.get('name','?'), op.get('params', []))
|
||
|
||
# ... (статистика по 5 группам, см. ниже)
|
||
```
|
||
|
||
### Когда перезапускать анализ
|
||
|
||
- После добавления новых сервисов
|
||
- После изменения структуры параметров в API
|
||
- При смене стенда (test/dev/prod)
|
||
|
||
Запуск:
|
||
```bash
|
||
python3 analyze_column_widths.py
|
||
```
|
||
|
||
---
|
||
|
||
## Результаты (стенд test, 2026-07-18)
|
||
|
||
**Объём данных:** 49 YAML-файлов, 775 параметров, 339 вложенных sub_params
|
||
|
||
| Колонка | Count | MAX (симв.) | AVG (симв.) | >50 | >100 | >200 |
|
||
|---|---|---|---|---|---|---|
|
||
| **Code** | 775 | 29 | 11 | 0% | 0% | 0% |
|
||
| **Type** | 775 | 15 | 9 | 0% | 0% | 0% |
|
||
| **Default** | 497 | 48 | 4 | 0% | 0% | 0% |
|
||
| **Description** | 488 | 635 | 69 | **55%** | **25%** | **3%** |
|
||
| **Constraints** | 247 | 199 | 46 | 27% | 6% | 0% |
|
||
|
||
### Выводы
|
||
|
||
1. **Code, Type, Default** — всегда короткие (макс 48 символов, обычно < 15). Им не нужно много места.
|
||
2. **Description** — основная колонка. 55% значений > 50 символов, 25% > 100. Ей нужна бОльшая часть ширины.
|
||
3. **Constraints** — есть только у 32% параметров (247 из 775). Длинные regex (> 100 символов) — исключение (у mariadb, clickhouse, postgres). Не нужно раздувать колонку ради 6% случаев — хватит `word-break: break-all`.
|
||
4. **Default** — есть у 64% параметров, всегда короткий (AVG 4 символа).
|
||
|
||
---
|
||
|
||
## Оптимальные ширины колонок
|
||
|
||
Используется `table-layout: fixed` — браузер жёстко соблюдает проценты.
|
||
|
||
### Основная таблица (`.resource-table:not(.resource-table-nested)`)
|
||
|
||
5 или 6 колонок: ID | Code | Type | (Default) | Description | Constraints
|
||
|
||
| Колонка | CSS-селектор | Ширина | Примечание |
|
||
|---|---|---|---|---|
|
||
| ID | `nth-child(1)` | 3% | |
|
||
| Code | `nth-child(2)` | 15% | |
|
||
| Type | `nth-child(3)` | 7% | |
|
||
| Default | авто | авто | только если есть (6 колонок) |
|
||
| Description | `nth-last-child(2)` | 48% | **главная колонка** |
|
||
| Constraints | `nth-last-child(1)` | 27% | `word-break: break-all` |
|
||
|
||
### Nested-таблица (`.resource-table-nested`)
|
||
|
||
7 колонок: ID | Code | Type | Required | Default | Description | Constraints
|
||
|
||
| Колонка | CSS-селектор | Ширина | Примечание |
|
||
|---|---|---|---|---|
|
||
| ID | `nth-child(1)` | 3% | |
|
||
| Code | `nth-child(2)` | 12% | |
|
||
| Type | `nth-child(3)` | 7% | |
|
||
| Required | `nth-child(4)` | 5% | |
|
||
| Default | `nth-child(5)` | 7% | |
|
||
| Description | `nth-child(6)` | 38% | **главная колонка** |
|
||
| Constraints | `nth-child(7)` | 28% | `word-break: break-all` |
|
||
|
||
---
|
||
|
||
## Принцип
|
||
|
||
> Если поле широкое только в 5% случаев — не надо рисовать его широким для всех.
|
||
> Description — всегда широкий. Constraints — редко широкий, пусть ломается.
|