Tisa.Common 2025.9.10.1120

Tisa.Common

Библиотека общих компонентов и утилит для .NET приложений, разработанная компанией ТИСА. Предоставляет набор базовых абстракций, расширений и примитивов для ускорения разработки приложений с использованием функциональных подходов и DDD паттернов.

Возможности

• Поддержка .NET 8.0, .NET 9.0 и .NET 10.0
• Система Result для обработки результатов операций без исключений
• Тип Maybe<T> для работы с опциональными значениями
• Базовые классы для DDD: ValueObject, AbstractEntity
• Расширенные перечисления EnumEnumeration<T>
• Система обработки ошибок Error
• Богатый набор методов расширения для коллекций, строк, дат и XML
• Маркеры жизненного цикла сервисов для DI

Установка

dotnet add package Tisa.Common

Основные компоненты

Result - Результаты операций

Тип Result позволяет обрабатывать результаты операций без использования исключений, что делает код более предсказуемым и производительным.

Базовое использование

using Tisa.Common.Primitives;

// Создание успешного результата
var success = Result.Success();

// Создание результата с данными
var dataResult = Result.Success(new { Name = "Test", Id = 1 });

// Создание результата с ошибкой
var errorResult = Result.Failure("Произошла ошибка");

// Проверка результата
if (dataResult.IsSuccess)
{
    var value = dataResult.Value; // Получение значения
}
else
{
    var error = dataResult.Error; // Получение ошибки
}

Работа с методами

public Result<User> GetUser(int id)
{
    if (id <= 0)
    {
        return Result.Failure<User>("Неверный идентификатор пользователя");
    }
    
    var user = _repository.FindById(id);
    if (user == null)
    {
        return Result.Failure<User>("Пользователь не найден");
    }
    
    return Result.Success(user);
}

// Использование
var result = GetUser(1);
result.Match(
    onSuccess: user => Console.WriteLine($"Пользователь: {user.Name}"),
    onFailure: error => Console.WriteLine($"Ошибка: {error.Detail}")
);

Цепочка операций

var result = GetUser(1)
    .Map(user => user.Name)
    .Map(name => name.ToUpper())
    .Bind(name => ValidateName(name));

// Комбинирование результатов
var combinedResult = Result.Combine(
    GetUser(1),
    GetUser(2)
);

Maybe - Опциональные значения

Тип Maybe<T> представляет опциональное значение, которое может присутствовать или отсутствовать.

Базовое использование

using Tisa.Common.Primitives;

// Создание Maybe со значением
var maybeValue = Maybe.Some(42);

// Создание Maybe без значения
var maybeNone = Maybe.None<int>();

// Проверка наличия значения
if (maybeValue.HasValue)
{
    var value = maybeValue.Value; // Получение значения
}

// Безопасное получение значения
var value = maybeValue.GetValueOrDefault(0); // Вернет 0, если значения нет
var valueOrThrow = maybeValue.GetValueOrThrow("Значение отсутствует");

Работа с коллекциями

var numbers = new List<int> { 1, 2, 3, 4, 5 };

// Поиск первого элемента
var first = numbers.TryFirst(x => x > 3); // Maybe<int>

// Поиск последнего элемента
var last = numbers.TryLast(x => x < 3); // Maybe<int>

// Поиск элемента
var found = numbers.TryFind(x => x == 3); // Maybe<int>

Преобразования

var maybe = Maybe.Some(10);

// Map - преобразование значения
var doubled = maybe.Map(x => x * 2); // Maybe<int> со значением 20

// Bind - цепочка операций
var result = maybe
    .Bind(x => x > 0 ? Maybe.Some(x * 2) : Maybe.None<int>())
    .Map(x => x.ToString());

// Преобразование в Result
var result = maybe.ToResult("Значение отсутствует");

EnumEnumeration - Расширенные перечисления

Класс EnumEnumeration<T> предоставляет типобезопасные перечисления с дополнительными возможностями.

Определение перечисления

using Tisa.Common.Primitives;

public sealed class UserRole : EnumEnumeration<UserRole>
{
    public static readonly UserRole Admin = new(1, nameof(Admin));
    public static readonly UserRole User = new(2, nameof(User));
    public static readonly UserRole Guest = new(3, nameof(Guest));

    private UserRole(int value, string name)
        : base(value, name)
    {
    }
}

Использование

// Получение по значению
var role = UserRole.FromValue(1); // Maybe<UserRole>

if (role.HasValue)
{
    Console.WriteLine(role.Value.Name); // "Admin"
}

// Получение по имени
var adminRole = UserRole.FromName("Admin"); // Maybe<UserRole>

// Получение всех значений
var allRoles = UserRole.ToList();

// Проверка существования
if (UserRole.ContainsValue(1))
{
    // Роль существует
}

ValueObject - Объекты-значения

Базовый класс для создания объектов-значений в DDD.

Определение ValueObject

using Tisa.Common.Primitives;

public sealed class Money : ValueObject
{
    public decimal Amount { get; }
    public string Currency { get; }

    public Money(decimal amount, string currency)
    {
        Amount = amount;
        Currency = currency;
    }

    protected override IEnumerable<object> GetEqualityComponents()
    {
        yield return Amount;
        yield return Currency;
    }
}

Использование

var money1 = new Money(100, "USD");
var money2 = new Money(100, "USD");

// Сравнение по значению
if (money1 == money2) // true
{
    Console.WriteLine("Суммы равны");
}

AbstractEntity - Базовые сущности

Базовый класс для создания сущностей в DDD.

Определение Entity

using Tisa.Common.Primitives;

public sealed class User : AbstractEntity<Guid>
{
    public string Name { get; private set; }
    public string Email { get; private set; }

    private User() { } // Для EF Core

    public User(Guid id, string name, string email)
        : base(id)
    {
        Name = name;
        Email = email;
    }
}

Использование

var user1 = new User(Guid.NewGuid(), "John", "john@example.com");
var user2 = new User(user1.Id, "John", "john@example.com");

// Сравнение по идентификатору
if (user1 == user2) // true, если Id совпадают
{
    Console.WriteLine("Один и тот же пользователь");
}

Error - Обработка ошибок

Класс Error предоставляет структурированную обработку ошибок.

Создание ошибок

using Tisa.Common.Errors;

// Различные типы ошибок
var notFound = Error.NotFound("User.NotFound", "Пользователь не найден");
var badRequest = Error.BadRequest("User.InvalidEmail", "Неверный формат email");
var conflict = Error.Conflict("User.EmailExists", "Email уже используется");
var unauthorized = Error.Unauthorized("Auth.InvalidToken", "Недействительный токен");
var forbidden = Error.Forbidden("Auth.AccessDenied", "Доступ запрещен");
var failure = Error.Failure("System.Error", "Внутренняя ошибка системы");

// Ошибка из исключения
try
{
    // код
}
catch (Exception ex)
{
    var error = Error.Failure(ex);
    // или
    var handledError = Error.HandleException(ex, ex => 
        ex is ArgumentException 
            ? Error.BadRequest("InvalidArgument", ex.Message)
            : Error.Failure(ex));
}

Использование с параметрами

var error = Error.NotFound("User.NotFound", "Пользователь с ID {0} не найден")
    .WithParams(userId);

Расширения (Extensions)

Библиотека предоставляет множество методов расширения для упрощения работы с базовыми типами.

Расширения для коллекций

using Tisa.Common.Extensions;

var list = new List<int> { 1, 2, 3 };

// Добавление диапазона
list.AddRange(new[] { 4, 5, 6 });

// Проверка наличия элементов
if (list.HasItems())
{
    // Коллекция не пуста
}

Расширения для строк

using Tisa.Common.Extensions;

string text = "Hello {0}";

// Заполнение параметров
var result = text.Fill("World"); // "Hello World"

// Повторение строки
var repeated = "abc".Repeat(3); // "abcabcabc"

// Проверки
if (text.IsEmpty())
{
    // Строка пуста
}

// Работа с Base64
var base64 = "Hello".ToBase64();
var decoded = base64.FromBase64();

// Извлечение подстрок
var left = "Hello World".Left(5); // "Hello"
var right = "Hello World".Right(5); // "World"

// Удаление нецифровых символов
var digits = "abc123def".RemoveNonDigits(); // "123"

Расширения для дат

using Tisa.Common.Extensions;

var date = DateTime.Now;

// Округление даты
var rounded = date.Round(TimeSpan.FromMinutes(15));

// Работа с TimeSpan
var span = TimeSpan.FromMinutes(90);
var formatted = span.ToHumanReadableString();

Расширения для XML

using Tisa.Common.Extensions;
using System.Xml.Linq;

var xElement = XElement.Parse("<root><item>value</item></root>");

// Удаление пространств имен
var withoutNamespaces = xElement.RemoveAllNamespaces();

// Преобразование в XmlDocument
var xmlDoc = xElement.ToXmlDocument();

// Условное добавление
xElement.Append(condition, new XElement("new", "value"));

ServiceLifetimes - Маркеры жизненного цикла

Интерфейсы для маркировки жизненного цикла сервисов в DI контейнере.

Использование

using Tisa.Common.ServiceLifetimes;

// Маркировка сервиса как Transient
public class MyService : IMyService, ITransient
{
    // Реализация
}

// Маркировка сервиса как Scoped
public class MyRepository : IMyRepository, IScoped
{
    // Реализация
}

Затем можно использовать автоматическую регистрацию через Scrutor или другие библиотеки:

services.Scan(scan => scan
    .FromAssemblyOf<MyService>()
    .AddClasses(classes => classes.AssignableTo<ITransient>())
    .AsImplementedInterfaces()
    .WithTransientLifetime()
    .AddClasses(classes => classes.AssignableTo<IScoped>())
    .AsImplementedInterfaces()
    .WithScopedLifetime());

Структура проекта

• Abstractions/ - Базовые интерфейсы (IResult, IMaybe, IEntity, IValue, IError, ICombine)
• Primitives/ - Базовые примитивы
  • Results/ - Система результатов операций
  • Maybe/ - Опциональные значения
  • ValueObject/ - Объекты-значения
  • EnumEnumeration.cs - Расширенные перечисления
  • AbstractEntity.cs - Базовые сущности
  • Request.cs, RequestT.cs - Базовые классы запросов
• Extensions/ - Методы расширения для стандартных типов
• ServiceLifetimes/ - Маркеры жизненного цикла сервисов (IScoped, ITransient)
• Errors/ - Система обработки ошибок

Требования

• .NET 8.0, .NET 9.0 или .NET 10.0

Дополнительные возможности

Функциональное программирование

Библиотека поддерживает функциональные подходы:

// Композиция функций
var result = GetUser(1)
    .Map(user => user.Email)
    .Bind(email => ValidateEmail(email))
    .Map(email => SendWelcomeEmail(email))
    .Match(
        onSuccess: () => Console.WriteLine("Email отправлен"),
        onFailure: error => Console.WriteLine($"Ошибка: {error.Detail}")
    );

Асинхронные операции

Поддержка асинхронных операций с Result и Maybe:

public async Task<Result<User>> GetUserAsync(int id)
{
    var user = await _repository.FindByIdAsync(id);
    return user != null 
        ? Result.Success(user) 
        : Result.Failure<User>("Пользователь не найден");
}

// Использование
var result = await GetUserAsync(1)
    .MapAsync(async user => await ProcessUserAsync(user));

Авторы

Команда разработчиков TISA

Лицензия

MIT License

Поддержка

Для получения поддержки или сообщения об ошибках, пожалуйста, напишите нам на support@tisn.ru