dotnet-writing-skills

// ✅ 推薦：不打算被繼承的類別應使用 sealed
public sealed class PaymentService(
    IPaymentRepository repository,
    ILogger<PaymentService> logger)
{
    public async Task ProcessAsync(Payment payment)
    {
        logger.LogInformation("Processing payment {Id}", payment.Id);
        await repository.SaveAsync(payment);
    }
}

// ✅ Service、Handler、Repository 通常應該是 sealed
public sealed class CreatePaymentHandler : IRequestHandler<CreatePaymentCommand, Result>
{
    // Implementation
}

// ❌ 避免：非必要的繼承可能性
public class PaymentService { } // 可被繼承，但通常不需要

// ✅ 僅在明確設計為可繼承時才不用 sealed
public abstract class BaseRepository<T> { } // 設計為基底類別
public class PaymentRepository : BaseRepository<Payment> { } // 繼承，但仍可 sealed

// ✅ 推薦（C# 12+）：結合 sealed 與 Primary Constructor
public sealed class PaymentService(
    IPaymentRepository repository,
    ILogger<PaymentService> logger)
{
    public async Task ProcessAsync(Payment payment)
    {
        logger.LogInformation("Processing payment {Id}", payment.Id);
        await repository.SaveAsync(payment);
    }
}

// ❌ 避免（舊風格）
public class PaymentService
{
    private readonly IPaymentRepository _repository;
    private readonly ILogger<PaymentService> _logger;
    
    public PaymentService(IPaymentRepository repository, ILogger<PaymentService> logger)
    {
        _repository = repository;
        _logger = logger;
    }
}

// ✅ 推薦：使用 required 屬性而非建構函式強制
public class CreateOrderRequest
{
    public required string CustomerId { get; init; }
    public required decimal Amount { get; init; }
    public DateTime? OrderDate { get; init; }
}

// 使用
var request = new CreateOrderRequest
{
    CustomerId = "C123",
    Amount = 100.50m
    // OrderDate 可選
};

// ✅ 推薦
string[] vowels = ["a", "e", "i", "o", "u"];
List<int> numbers = [1, 2, 3, 4, 5];
int[] combined = [..array1, ..array2];

// ❌ 避免
string[] vowels = new[] { "a", "e", "i", "o", "u" };

// ✅ 推薦
namespace BookKeeper.Api.Features.Payments;

public class PaymentService { }

// ❌ 避免（浪費縮排層級）
namespace BookKeeper.Api.Features.Payments
{
    public class PaymentService { }
}

// ✅ 推薦：多行字串、JSON、SQL
var sql = """
    SELECT *
    FROM orders
    WHERE customer_id = @customerId
        AND status = 'Pending'
    """;

// ❌ 避免：使用跳脫字元
var sql = "SELECT *\nFROM orders\nWHERE customer_id = @customerId";

// ✅ 短字串串連：使用 String Interpolation
string displayName = $"{user.LastName}, {user.FirstName}";

// ✅ 迴圈中大量字串：使用 StringBuilder
var builder = new StringBuilder();
for (var i = 0; i < 10000; i++)
{
    builder.Append(phrase);
}

// ✅ 表達式字串插值
Console.WriteLine($"{student.Last} Score: {student.Score}");

// ✅ 推薦：Result Pattern 用於業務邏輯錯誤
public record Result<T>
{
    public T? Value { get; init; }
    public Error? Error { get; init; }
    public bool IsSuccess => Error is null;
    
    public static Result<T> Success(T value) => new() { Value = value };
    public static Result<T> Failure(Error error) => new() { Error = error };
}

// 使用
public async Task<Result<Payment>> ProcessPaymentAsync(PaymentRequest request)
{
    if (request.Amount <= 0)
        return Result<Payment>.Failure(new Error("Payment.InvalidAmount", "Amount must be greater than 0"));
    
    var payment = await _repository.SaveAsync(request);
    return Result<Payment>.Success(payment);
}

// ❌ 避免：使用例外處理業務邏輯錯誤
public async Task<Payment> ProcessPaymentAsync(PaymentRequest request)
{
    if (request.Amount <= 0)
        throw new InvalidOperationException("Invalid amount"); // 不應該用例外
}

// ✅ 僅捕捉可以處理的例外
try
{
    return Math.Sqrt((x1 - x2) * (x1 - x2) + (y1 - y2) * (y1 - y2));
}
catch (ArithmeticException ex)
{
    _logger.LogError(ex, "Arithmetic overflow");
    throw; // 重新拋出
}

// ✅ 使用 using 簡化 Dispose
using var connection = new SqlConnection(connectionString);
await connection.OpenAsync();

// ❌ 避免：捕捉一般例外
catch (Exception ex) { } // 過於寬泛

// ✅ 使用有意義的查詢變數名稱
var seattleCustomers = from customer in Customers
                       where customer.City == "Seattle"
                       select customer.Name;

// ✅ 使用別名確保 Pascal Case
var localDistributors =
    from customer in Customers
    join distributor in Distributors on customer.City equals distributor.City
    select new { Customer = customer, Distributor = distributor };

// ✅ where 子句優先（減少資料集）
var seattleCustomers = from customer in Customers
                       where customer.City == "Seattle"
                       orderby customer.Name
                       select customer;

// ✅ 使用多個 from 存取內部集合
var highScores = from student in students
                 from score in student.Scores
                 where score > 90
                 select new { Last = student.LastName, score };

// ❌ 避免：使用 join 來存取集合

// ✅ 型別明確時使用 var
var message = "This is clearly a string.";
var customer = new Customer();
var result = await GetCustomerAsync(id);

// ✅ for 迴圈使用 var
for (var i = 0; i < count; i++) { }

// ❌ 避免：型別不明確時使用 var
var count = GetCount(); // 回傳型別未知
int count = GetCount(); // 明確

// ✅ foreach 使用明確型別（除非是匿名型別）
foreach (Customer customer in customers) { }

// ✅ LINQ 查詢結果使用 var（通常是匿名型別）
var results = from c in customers
              select new { c.Name, c.City };

// ✅ 使用 Func<> 和 Action<> 而非自訂委派
Action<string> log = message => _logger.LogInformation(message);
Func<int, int, int> add = (x, y) => x + y;

// ✅ Lambda 用於簡短事件處理
button.Click += (s, e) => MessageBox.Show("Clicked!");

// ❌ 避免：定義新委派型別（除非必要）
public delegate void CustomDelegate(string message);

// ✅ 使用 && 和 || （短路求值）
if ((divisor != 0) && (dividend / divisor) is var result)
{
    Console.WriteLine($"Result: {result}");
}

// ❌ 避免：& 和 |（會評估兩邊）
if ((divisor != 0) & (dividend / divisor > 0)) { } // 危險

// ✅ new 運算子簡潔形式
var customer = new Customer();
Customer customer = new(); // 型別已知時

// ✅ 使用物件初始設定式
var order = new Order
{
    Id = 123,
    Amount = 100.50m,
    Status = OrderStatus.Pending
};

// ✅ Allman 大括號風格（各自獨立一行）
public void ProcessOrder()
{
    if (IsValid())
    {
        Save();
    }
}

// ✅ 每行一個陳述式
int x = 1;
int y = 2;

// ✅ 運算式使用括號清楚分隔
if ((startX > endX) && (startX > previousX))
{
    // Take action
}

// ✅ 方法之間至少一個空白行
public void Method1()
{
    // Implementation
}

public void Method2()
{
    // Implementation
}

// ✅ 推薦：using 放在 namespace 外部（明確完整名稱）
using Microsoft.EntityFrameworkCore;
using BookKeeper.Api.Database;

namespace BookKeeper.Api.Features.Payments;

public class PaymentService { }

// ❌ 避免：using 在 namespace 內部（相對名稱，可能衝突）
namespace BookKeeper.Api.Features.Payments
{
    using Microsoft.EntityFrameworkCore;
}

Features/
├── Payments/
│   ├── CreatePayment/
│   │   ├── CreatePaymentCommand.cs       # Command 定義
│   │   ├── CreatePaymentValidator.cs     # FluentValidation
│   │   ├── CreatePaymentHandler.cs       # MediatR Handler
│   │   └── CreatePaymentEndpoint.cs      # Minimal API Endpoint
│   ├── GetPayment/
│   │   ├── GetPaymentQuery.cs
│   │   ├── GetPaymentHandler.cs
│   │   └── GetPaymentEndpoint.cs
│   └── Shared/
│       └── PaymentErrors.cs              # Shared errors for feature

// ✅ Command（修改狀態）
public record CreatePaymentCommand(
    string CustomerId,
    decimal Amount,
    string Description) : IRequest<Result<PaymentResponse>>;

// ✅ Query（讀取資料）
public record GetPaymentQuery(string PaymentId) : IRequest<Result<PaymentResponse>>;

// ✅ Handler
public class CreatePaymentHandler(
    ApplicationDbContext context,
    ILogger<CreatePaymentHandler> logger)
    : IRequestHandler<CreatePaymentCommand, Result<PaymentResponse>>
{
    public async Task<Result<PaymentResponse>> Handle(
        CreatePaymentCommand command,
        CancellationToken cancellationToken)
    {
        // Business logic
        var payment = Payment.Create(command.CustomerId, command.Amount);
        
        context.Payments.Add(payment);
        await context.SaveChangesAsync(cancellationToken);
        
        return Result<PaymentResponse>.Success(new PaymentResponse(payment.Id));
    }
}

// ✅ IEndpoint 模式
public class CreatePaymentEndpoint : IEndpoint
{
    public void MapEndpoint(IEndpointRouteBuilder app)
    {
        app.MapPost("/api/payments", async (
            CreatePaymentRequest request,
            ISender sender,
            CancellationToken ct) =>
        {
            var command = new CreatePaymentCommand(
                request.CustomerId,
                request.Amount,
                request.Description);
            
            var result = await sender.Send(command, ct);
            
            return result.IsSuccess
                ? Results.Ok(result.Value)
                : Results.BadRequest(result.Error);
        })
        .WithName("CreatePayment")
        .WithTags("Payments")
        .Produces<PaymentResponse>(StatusCodes.Status200OK)
        .ProducesProblem(StatusCodes.Status400BadRequest);
    }
}

// ❌ N+1 問題
var orders = await context.Orders.ToListAsync();
foreach (var order in orders)
{
    var customer = await context.Customers.FindAsync(order.CustomerId); // N 次查詢
}

// ✅ 使用 Include
var orders = await context.Orders
    .Include(o => o.Customer)
    .ToListAsync();

// ✅ 使用 Select 投影（更高效）
var orderDtos = await context.Orders
    .Select(o => new OrderDto
    {
        OrderId = o.Id,
        CustomerName = o.Customer.Name
    })
    .ToListAsync();

// ✅ 唯讀查詢使用 AsNoTracking
var customers = await context.Customers
    .AsNoTracking()
    .Where(c => c.City == "Seattle")
    .ToListAsync();

// ✅ 使用 Skip/Take 分頁
public async Task<PagedResult<Customer>> GetCustomersAsync(int page, int pageSize)
{
    var query = context.Customers.AsNoTracking();
    
    var total = await query.CountAsync();
    
    var items = await query
        .OrderBy(c => c.Name)
        .Skip((page - 1) * pageSize)
        .Take(pageSize)
        .ToListAsync();
    
    return new PagedResult<Customer>(items, total, page, pageSize);
}

// ✅ 使用 Task.WhenAll 並行執行獨立查詢
var customerTask = context.Customers.FindAsync(customerId);
var ordersTask = context.Orders.Where(o => o.CustomerId == customerId).ToListAsync();
var paymentsTask = context.Payments.Where(p => p.CustomerId == customerId).ToListAsync();

await Task.WhenAll(customerTask, ordersTask, paymentsTask);

var customer = await customerTask;
var orders = await ordersTask;
var payments = await paymentsTask;

// ⚠️ 警告：DbContext 不是執行緒安全，需使用 IDbContextFactory

// ✅ 單行註解簡短說明
// Calculate the total with tax

// ✅ XML 註解用於公開 API
/// <summary>
/// Processes a payment transaction.
/// </summary>
/// <param name="request">The payment request details.</param>
/// <param name="cancellationToken">Cancellation token.</param>
/// <returns>A result containing the payment response or error.</returns>
public async Task<Result<PaymentResponse>> ProcessPaymentAsync(
    PaymentRequest request,
    CancellationToken cancellationToken)
{
    // Implementation
}

// ❌ 避免：多行註解 /* */（除非必要）
// ❌ 避免：過時的註解
// ❌ 避免：顯而易見的註解
// i++; // Increment i by 1

// ✅ 使用參數化查詢（EF Core 自動處理）
var customer = await context.Customers
    .FirstOrDefaultAsync(c => c.Email == email);

// ❌ 避免：字串串連 SQL（SQL Injection 風險）
var sql = $"SELECT * FROM Customers WHERE Email = '{email}'"; // 危險

// ✅ 驗證輸入
if (string.IsNullOrWhiteSpace(request.Email))
    return Result<Customer>.Failure(Errors.Customer.EmailRequired);

// ✅ 使用 FluentValidation
public class CreateCustomerValidator : AbstractValidator<CreateCustomerRequest>
{
    public CreateCustomerValidator()
    {
        RuleFor(x => x.Email)
            .NotEmpty()
            .EmailAddress();
        
        RuleFor(x => x.Amount)
            .GreaterThan(0)
            .LessThanOrEqualTo(10000);
    }
}