development-workflow

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

.NET Development Workflow

.NET开发工作流

Workflow Overview

工作流概述

┌─────────────────────────────────────────────────────────────────┐
│                    DEVELOPMENT WORKFLOW                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌──────────────┐                                               │
│  │  Understand  │  Read requirements, explore codebase          │
│  │    Task      │                                               │
│  └──────────────┘                                               │
│         │                                                       │
│         ▼                                                       │
│  ┌──────────────┐                                               │
│  │  Implement   │  Write code following patterns                │
│  │   Changes    │                                               │
│  └──────────────┘                                               │
│         │                                                       │
│         ▼                                                       │
│  ┌──────────────┐     ┌──────────────┐                         │
│  │   Validate   │────▶│   Report     │                         │
│  │ Build/Test/  │     │   Results    │                         │
│  │   Analyze    │     │              │                         │
│  └──────────────┘     └──────────────┘                         │
│         │                    │                                  │
│         ▼                    ▼                                  │
│    ┌─────────┐         ┌──────────┐                            │
│    │  PASS?  │───NO───▶│   Fix    │                            │
│    └─────────┘         │  Issues  │                            │
│         │              └──────────┘                            │
│         │                    │                                  │
│        YES                   │                                  │
│         │                    │                                  │
│         ▼                    │                                  │
│  ┌──────────────┐           │                                  │
│  │   Ready to   │◀──────────┘                                  │
│  │    Commit    │         (re-validate)                        │
│  └──────────────┘                                              │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                    DEVELOPMENT WORKFLOW                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌──────────────┐                                               │
│  │  Understand  │  Read requirements, explore codebase          │
│  │    Task      │                                               │
│  └──────────────┘                                               │
│         │                                                       │
│         ▼                                                       │
│  ┌──────────────┐                                               │
│  │  Implement   │  Write code following patterns                │
│  │   Changes    │                                               │
│  └──────────────┘                                               │
│         │                                                       │
│         ▼                                                       │
│  ┌──────────────┐     ┌──────────────┐                         │
│  │   Validate   │────▶│   Report     │                         │
│  │ Build/Test/  │     │   Results    │                         │
│  │   Analyze    │     │              │                         │
│  └──────────────┘     └──────────────┘                         │
│         │                    │                                  │
│         ▼                    ▼                                  │
│    ┌─────────┐         ┌──────────┐                            │
│    │  PASS?  │───NO───▶│   Fix    │                            │
│    └─────────┘         │  Issues  │                            │
│         │              └──────────┘                            │
│         │                    │                                  │
│        YES                   │                                  │
│         │                    │                                  │
│         ▼                    │                                  │
│  ┌──────────────┐           │                                  │
│  │   Ready to   │◀──────────┘                                  │
│  │    Commit    │         (re-validate)                        │
│  └──────────────┘                                              │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Phase 1: Understand the Task

阶段1：理解任务

Feature Implementation

功能实现

Read the feature requirements/user story
Identify affected components
Check existing patterns in codebase
Plan the implementation approach

阅读功能需求/用户故事
确定受影响的组件
查看代码库中的现有模式
规划实现方案

Bug Fix

Bug修复

Reproduce the bug
Identify root cause
Find related code
Plan the fix

复现Bug
确定根本原因
找到相关代码
规划修复方案

Refactoring

代码重构

Understand current implementation
Identify what needs to change
Ensure test coverage exists
Plan incremental changes

理解当前实现
确定需要修改的内容
确保存在测试覆盖
规划增量式修改

Phase 2: Implement Changes

阶段2：实施修改

Follow Existing Patterns

遵循现有模式

csharp

// Find existing patterns
// Look for similar implementations in the codebase
// Follow established conventions

// Example: If services follow this pattern
public class ExistingService : IExistingService
{
    private readonly IRepository _repository;
    private readonly ILogger<ExistingService> _logger;

    public ExistingService(IRepository repository, ILogger<ExistingService> logger)
    {
        _repository = repository;
        _logger = logger;
    }
}

// New service should follow same pattern
public class NewService : INewService
{
    private readonly IRepository _repository;
    private readonly ILogger<NewService> _logger;

    public NewService(IRepository repository, ILogger<NewService> logger)
    {
        _repository = repository;
        _logger = logger;
    }
}

csharp

// Find existing patterns
// Look for similar implementations in the codebase
// Follow established conventions

// Example: If services follow this pattern
public class ExistingService : IExistingService
{
    private readonly IRepository _repository;
    private readonly ILogger<ExistingService> _logger;

    public ExistingService(IRepository repository, ILogger<ExistingService> logger)
    {
        _repository = repository;
        _logger = logger;
    }
}

// New service should follow same pattern
public class NewService : INewService
{
    private readonly IRepository _repository;
    private readonly ILogger<NewService> _logger;

    public NewService(IRepository repository, ILogger<NewService> logger)
    {
        _repository = repository;
        _logger = logger;
    }
}

Make Small, Incremental Changes

进行小步增量式修改

One logical change at a time
Build after each change to catch errors early
Run relevant tests frequently
Keep commits focused

每次只做一个逻辑相关的修改
每次修改后构建，尽早发现错误
频繁运行相关测试
保持提交内容聚焦

Phase 3: Validate Changes

阶段3：验证修改

Validation Steps

验证步骤

bash

undefined

bash

undefined

1. Build (catch compilation errors)

dotnet build --no-incremental

2. Run tests (verify behavior)

dotnet test --no-build

3. Static analysis (code quality)

dotnet build /p:TreatWarningsAsErrors=true dotnet format --verify-no-changes

undefined

dotnet build /p:TreatWarningsAsErrors=true dotnet format --verify-no-changes

undefined

Quality Gates

质量门禁

Gate	Requirement	Blocking
Build	0 errors	Yes
Tests	100% pass	Yes
Critical Warnings	0	No
All Warnings	< 10	No

门禁	要求	是否阻塞
构建	0个错误	是
测试	100%通过	是
严重警告	0个	否
所有警告	<10个	否

Phase 4: Fix Issues

阶段4：修复问题

Build Errors

构建错误

Read error message carefully
Go to the file and line indicated
Fix the issue
Rebuild to verify

仔细阅读错误信息
定位到指定的文件和行
修复问题
重新构建验证

Test Failures

测试失败

Read the assertion failure
Check expected vs actual
Determine if test or code is wrong
Fix and re-run test

阅读断言失败信息
对比预期结果与实际结果
判断是测试还是代码存在问题
修复后重新运行测试

Analysis Warnings

分析警告

Review each warning
Apply fix or suppress with justification
Use
```
dotnet format
```
for auto-fixable issues

逐一检查每个警告
修复或合理地抑制警告
使用
```
dotnet format
```
修复可自动修正的问题

Validation Before Commit

提交前的验证

Checklist

检查清单

```
dotnet build
```
succeeds with no errors
```
dotnet test
```
passes all tests
No new critical analyzer warnings
Code follows existing patterns
Changes are focused on the task

```
dotnet build
```
无错误执行成功
```
dotnet test
```
所有测试通过
无新增的严重分析器警告
代码遵循现有模式
修改内容围绕任务聚焦

Commands

命令

bash

undefined

bash

undefined

Full validation

dotnet build --no-incremental &&
dotnet test --no-build &&
dotnet format --verify-no-changes

undefined

dotnet build --no-incremental &&
dotnet test --no-build &&
dotnet format --verify-no-changes

undefined

Best Practices

最佳实践

Code Organization

代码组织

csharp

// Group related code
// 1. Fields
private readonly IService _service;

// 2. Constructors
public MyClass(IService service) => _service = service;

// 3. Public methods
public void Execute() { }

// 4. Private methods
private void Helper() { }

csharp

// Group related code
// 1. Fields
private readonly IService _service;

// 2. Constructors
public MyClass(IService service) => _service = service;

// 3. Public methods
public void Execute() { }

// 4. Private methods
private void Helper() { }

Error Handling

错误处理

csharp

// Be specific with exceptions
public User GetUser(int id)
{
    var user = _repository.Find(id);
    if (user == null)
        throw new EntityNotFoundException($"User {id} not found");
    return user;
}

// Use guard clauses
public void Process(Request request)
{
    ArgumentNullException.ThrowIfNull(request);
    ArgumentException.ThrowIfNullOrEmpty(request.Name);

    // Main logic
}

csharp

// Be specific with exceptions
public User GetUser(int id)
{
    var user = _repository.Find(id);
    if (user == null)
        throw new EntityNotFoundException($"User {id} not found");
    return user;
}

// Use guard clauses
public void Process(Request request)
{
    ArgumentNullException.ThrowIfNull(request);
    ArgumentException.ThrowIfNullOrEmpty(request.Name);

    // Main logic
}

Async/Await

csharp

// Always use async suffix
public async Task<User> GetUserAsync(int id)
{
    return await _repository.FindAsync(id);
}

// Don't block on async
// BAD
var user = GetUserAsync(id).Result;

// GOOD
var user = await GetUserAsync(id);

csharp

// Always use async suffix
public async Task<User> GetUserAsync(int id)
{
    return await _repository.FindAsync(id);
}

// Don't block on async
// BAD
var user = GetUserAsync(id).Result;

// GOOD
var user = await GetUserAsync(id);

Dependency Injection

依赖注入

csharp

// Register services
services.AddScoped<IUserService, UserService>();
services.AddSingleton<ICacheService, MemoryCacheService>();
services.AddTransient<IEmailSender, SmtpEmailSender>();

// Inject via constructor
public class UserController
{
    private readonly IUserService _userService;

    public UserController(IUserService userService)
    {
        _userService = userService;
    }
}

csharp

// Register services
services.AddScoped<IUserService, UserService>();
services.AddSingleton<ICacheService, MemoryCacheService>();
services.AddTransient<IEmailSender, SmtpEmailSender>();

// Inject via constructor
public class UserController
{
    private readonly IUserService _userService;

    public UserController(IUserService userService)
    {
        _userService = userService;
    }
}

Common Patterns

常见模式

See patterns.md for detailed implementation patterns.

详见patterns.md获取详细的实现模式。