crank/docs/rust-code-rules.md

Rust Code Rules

1. Назначение документа

Этот документ фиксирует Rust-specific правила кода для проекта:

• toolchain;
• linting;
• formatting;
• ошибки;
• async;
• ownership;
• visibility;
• dependency hygiene.

Цель документа - убрать плавающие договоренности по стилю и практике командной Rust-разработки.

2. Toolchain

2.1. Версия Rust

Для проекта должен быть зафиксирован rust-toolchain.toml.

В нем должны быть определены:

• стабильный channel;
• protocol;
• при необходимости components.

Рекомендуемый состав:

• rustfmt
• clippy

2.2. MSRV

Нужно зафиксировать MSRV - минимально поддерживаемую версию Rust.

Правило:

• без необходимости не использовать возможности языка новее зафиксированного MSRV;
• обновление MSRV - это отдельное осознанное решение.

3. Formatting и linting

3.1. Formatting

Обязательное правило:

• весь код форматируется через cargo fmt.

Ручной стиль форматирования не обсуждается и не поддерживается.

3.2. Clippy

Обязательное правило:

• cargo clippy --all-targets --all-features -- -D warnings

Предупреждения считаются ошибками, если нет явно зафиксированного исключения.

3.3. CI quality gates

Минимально в CI должны запускаться:

• cargo fmt --check
• cargo clippy --all-targets --all-features -- -D warnings
• cargo test

Опционально позже:

• cargo deny
• cargo audit

4. unsafe

Для проекта принимается правило:

• unsafe запрещен по умолчанию.

Если когда-либо потребуется unsafe, то:

• это должно быть отдельное осознанное решение;
• причина должна быть технически обоснована;
• блок должен быть минимальным;
• вокруг него должны быть тесты.

Для MVP можно считать:

• unsafe_code = deny

5. Panic policy

В production code запрещены:

• unwrap()
• expect()
• todo!()
• unimplemented!()
• dbg!()
• необоснованные panic!()

Допускается:

• в тестах;
• в очень раннем bootstrap-коде, если это действительно аварийное завершение и не часть доменной логики.

Базовое правило:

• ошибки возвращаются через Result, а не через panic.

6. Правила ошибок

6.1. Domain и service errors

В домене и сервисах использовать типизированные ошибки.

Рекомендуемо:

• thiserror

6.2. Application boundary

На верхних слоях приложений допускается агрегирование ошибок, если это упрощает wiring.

При необходимости:

• anyhow только на внешних границах приложения, не в доменной модели.

6.3. Error context

Ошибка должна сохранять стадию отказа:

• schema
• mapping
• adapter
• persistence
• external service
• internal runtime

7. Visibility rules

Правило:

• по умолчанию все приватное;
• pub(crate) предпочтительнее pub;
• публичный API должен быть минимальным.

Нельзя:

• открывать модуль наружу "на всякий случай";
• делать pub просто ради удобства из соседнего файла;
• реэкспортировать целые деревья модулей без причины.

8. Ownership и данные

8.1. Клонирование

Правило:

• не клонировать данные без необходимости;
• клон должен быть осознанным, а не способом обойти borrow checker без понимания причины.

8.2. Shared mutability

Правило:

• не использовать Arc<Mutex<_>> как универсальный контейнер состояния;
• shared mutability допускается только там, где она действительно нужна по архитектуре.

8.3. ID types

Идентификаторы должны быть отдельными типами, а не просто String.

Примеры:

• OperationId
• DescriptorId
• AuthProfileId

9. Async rules

9.1. Где допускается async

async используется только там, где есть:

• I/O;
• network;
• storage;
• async boundary приложения.

9.2. Где async не нужен

Нельзя превращать:

• schema validation;
• mapping;
• чистую доменную логику;
• небольшие derived methods

в async fn без причины.

9.3. tokio

tokio должен находиться:

• в приложениях;
• в I/O слоях;
• в адаптерах и runtime orchestration, если там есть реальный async.

Доменный слой не должен зависеть от tokio.

10. API design rules

10.1. Конструкторы

Использовать:

• new() для гарантированно валидного и простого создания;
• try_new() там, где есть валидация и возможна ошибка.

10.2. Builders

Если структура имеет много параметров и прямой конструктор становится нечитаемым, допускается builder.

Но:

• builder не должен маскировать плохую модель данных;
• builder не должен использоваться как замена нормальной декомпозиции.

10.3. DTO отдельно от domain

Если HTTP payload начинает расходиться с доменной моделью, нужно вводить отдельный DTO слой.

Нельзя:

• тащить serde-ориентированный API payload прямо в домен только ради удобства.

11. Dependency rules

11.1. Внешние crates

Правило:

• сначала использовать std;
• потом существующие внутренние abstractions;
• только потом тянуть новый внешний crate.

Нельзя:

• добавлять зависимость "на всякий случай";
• дублировать crates с пересекающейся функцией без причины.

11.2. Макросы

Правило:

• не злоупотреблять макросами там, где обычный Rust-код читается лучше;
• derive-макросы допустимы;
• сложные процедурные макросы без сильной причины не нужны.

12. Serialization rules

12.1. JSON/YAML

Правило:

• доменная модель одна;
• JSON и YAML - только два формата сериализации;
• нельзя допускать, чтобы YAML export стал отдельной несовместимой моделью.

12.2. Secrets

Никогда не сериализовать:

• реальные токены;
• пароли;
• API keys

в exports, logs и test snapshots.

13. Тестовые практики на уровне Rust-кода

Минимально:

• unit tests рядом с модулем или в tests;
• integration tests для crate boundaries;
• фикстуры для schema/mapping/proto/yaml roundtrip.

Полезное правило:

• баг сначала воспроизводится тестом, потом фиксится кодом.

14. Что часто запрещают в Rust-командах

Практически всегда под запретом:

• unwrap() в production code;
• unsafe без review;
• giant modules;
• giant enums со всем подряд;
• giant services, где смешаны orchestration и transport;
• абстракции "на будущее" без второго реального кейса.

15. Практический итог

Для этого проекта правильный Rust-профиль такой:

• фиксированный toolchain;
• обязательные fmt и clippy;
• unsafe запрещен по умолчанию;
• panics запрещены в production code;
• ошибки типизированы;
• pub минимизируется;
• async только на реальных async boundaries;
• код читается за счет имен и декомпозиции, а не за счет комментариев.