Hua/Hua.Todo

Fork 0

Files

T

ShaoHua 141b3112a4 doc:整理文档

2026-04-06 23:25:57 +08:00

13 KiB

Raw Permalink Blame History

Hua.Todo 代码规范文档 v1.1.0

1. 概述

本文档定义 Hua.Todo 项目的代码规范，包括 C#、JavaScript/TypeScript、Vue.js 和其他相关技术的编码标准。遵循这些规范有助于提高代码质量、可读性和可维护性。

2. 通用规范

2.1 命名约定

使用有意义的名称: 变量、函数、类名应清晰表达其用途
避免缩写: 除非是广泛认知的缩写（如 ID、URL、API）
一致性: 在整个项目中保持命名风格一致

2.2 注释规范

公共 API 必须添加 XML 文档注释
复杂逻辑添加行内注释
避免注释显而易见的代码
保持注释与代码同步更新

2.3 代码格式化

使用统一的代码格式化工具
保持一致的缩进和空格
每行代码不超过 120 字符
文件末尾保留一个空行

3. C# 代码规范

3.1 命名规范

类和接口

// 类名使用 PascalCase
public class TaskService
{
}

// 接口名使用 PascalCase，以 I 开头
public interface ITaskService
{
}

方法和属性

// 方法名使用 PascalCase
public Task<List<Task>> GetTasksAsync()
{
}

// 属性名使用 PascalCase
public string Title { get; set; }

变量和参数

// 私有字段使用 _camelCase
private readonly ITaskRepository _taskRepository;

// 局部变量使用 camelCase
var taskList = await GetTasksAsync();

// 方法参数使用 camelCase
public void CreateTask(string title, TaskPriority priority)
{
}

常量

// 常量使用 PascalCase
public const int MaxTaskTitleLength = 200;

3.2 代码组织

文件结构

// 1. using 语句（按字母顺序）
using System;
using System.Collections.Generic;
using System.Threading.Tasks;

// 2. 命名空间
namespace Hua.Todo.Api.Services;

// 3. XML 文档注释
/// <summary>
/// 任务服务实现
/// </summary>
public class TaskService : ITaskService
{
    // 4. 私有字段
    private readonly ITaskRepository _taskRepository;

    // 5. 构造函数
    public TaskService(ITaskRepository taskRepository)
    {
        _taskRepository = taskRepository;
    }

    // 6. 公共方法
    public async Task<List<Task>> GetTasksAsync()
    {
        // 实现
    }

    // 7. 私有方法
    private bool ValidateTask(Task task)
    {
        // 实现
    }
}

命名空间组织

每个文件只包含一个命名空间
命名空间结构应与目录结构一致
使用 . 分隔层级

3.3 编码规范

异步编程

// 异步方法应以 Async 结尾
public async Task<Task> GetTaskByIdAsync(int id)
{
    return await _taskRepository.GetByIdAsync(id);
}

// 使用 await 而非 .Result 或 .Wait
var task = await GetTaskByIdAsync(id);

// 使用 ConfigureAwait(false) 在库代码中
public async Task<List<Task>> GetTasksAsync()
{
    return await _taskRepository.GetAllAsync().ConfigureAwait(false);
}

依赖注入

// 优先使用构造函数注入
public class TaskService : ITaskService
{
    private readonly ITaskRepository _taskRepository;
    private readonly ILogger<TaskService> _logger;

    public TaskService(ITaskRepository taskRepository, ILogger<TaskService> logger)
    {
        _taskRepository = taskRepository;
        _logger = logger;
    }
}

异常处理

// 使用具体的异常类型
public async Task<Task> GetTaskByIdAsync(int id)
{
    var task = await _taskRepository.GetByIdAsync(id);
    
    if (task == null)
    {
        throw new NotFoundException($"Task with id {id} not found");
    }
    
    return task;
}

// 使用 using 语句管理资源
using var context = new TodoDbContext();

LINQ 使用

// 优先使用方法语法
var completedTasks = tasks.Where(t => t.IsCompleted).ToList();

// 复杂查询使用查询语法
var query = from task in tasks
            where task.IsCompleted
            orderby task.CreatedAt descending
            select task;

3.4 文档注释

/// <summary>
/// 获取指定 ID 的任务
/// </summary>
/// <param name="id">任务 ID</param>
/// <returns>任务对象</returns>
/// <exception cref="NotFoundException">当任务不存在时抛出</exception>
public async Task<Task> GetTaskByIdAsync(int id)
{
    // 实现
}

4. JavaScript/TypeScript 代码规范

4.1 命名规范

变量和函数

// 变量使用 camelCase
const taskList = [];
let currentTask = null;

// 函数使用 camelCase
function getTasks() {
  // 实现
}

// 常量使用 UPPER_SNAKE_CASE
const MAX_TASK_TITLE_LENGTH = 200;

类和接口

// 类名使用 PascalCase
class TaskService {
  // 实现
}

// 接口名使用 PascalCase
interface Task {
  id: number;
  title: string;
}

// 类型别名使用 PascalCase
type TaskPriority = 'high' | 'medium' | 'low';

4.2 代码组织

文件结构

// 1. 导入语句
import { ref, computed } from 'vue';
import { useTaskStore } from '@/stores/tasks';
import type { Task } from '@/types/task';

// 2. 类型定义
interface TaskForm {
  title: string;
  priority: TaskPriority;
}

// 3. 常量定义
const DEFAULT_PRIORITY: TaskPriority = 'medium';

// 4. 组合式函数或组件
export function useTasks() {
  // 实现
}

模块导入

// 优先使用 ES6 模块语法
import { ref } from 'vue';
import axios from 'axios';

// 导出使用具名导出
export function useTasks() {
  // 实现
}

export default useTasks;

4.3 TypeScript 规范

类型定义

// 为所有函数参数和返回值添加类型
function getTaskById(id: number): Task | null {
  // 实现
}

// 使用接口定义对象类型
interface Task {
  id: number;
  title: string;
  priority: TaskPriority;
  isCompleted: boolean;
  createdAt: Date;
}

// 使用类型别名定义联合类型
type TaskPriority = 'high' | 'medium' | 'low';

// 使用泛型提高代码复用性
interface ApiResponse<T> {
  data: T;
  message: string;
}

类型断言

// 优先使用类型守卫而非类型断言
function isTask(obj: unknown): obj is Task {
  return typeof obj === 'object' && obj !== null && 'id' in obj;
}

// 避免使用 as any
const task = response.data as Task; // 避免

4.4 异步编程

// 使用 async/await 而非 Promise 链
async function getTasks(): Promise<Task[]> {
  const response = await axios.get('/api/tasks');
  return response.data;
}

// 错误处理
try {
  const tasks = await getTasks();
} catch (error) {
  console.error('Failed to fetch tasks:', error);
}

5. Vue.js 代码规范

5.1 组件命名

<!-- 组件名使用 PascalCase -->
<script setup lang="ts">
// 组件名应与文件名一致
</script>

<template>
  <!-- 模板中使用 kebab-case -->
  <task-item :task="task" />
</template>

5.2 组件结构

<template>
  <!-- 1. 模板 -->
  <div class="task-list">
    <task-item
      v-for="task in tasks"
      :key="task.id"
      :task="task"
    />
  </div>
</template>

<script setup lang="ts">
// 2. 导入
import { ref, computed } from 'vue';
import { useTaskStore } from '@/stores/tasks';
import TaskItem from './TaskItem.vue';

// 3. Props 定义
interface Props {
  filter: 'all' | 'active' | 'completed';
}

const props = withDefaults(defineProps<Props>(), {
  filter: 'all'
});

// 4. Emits 定义
const emit = defineEmits<{
  (e: 'task-created', task: Task): void;
}>();

// 5. 响应式状态
const taskStore = useTaskStore();
const tasks = computed(() => taskStore.filteredTasks(props.filter));

// 6. 方法
const handleCreateTask = async (title: string) => {
  const task = await taskStore.createTask(title);
  emit('task-created', task);
};
</script>

<style scoped>
/* 6. 样式 */
.task-list {
  padding: 16px;
}
</style>

5.3 组合式函数规范

// composables/useTasks.ts
import { ref, computed } from 'vue';
import { useTaskStore } from '@/stores/tasks';

export function useTasks() {
  const taskStore = useTaskStore();
  const loading = ref(false);
  const error = ref<string | null>(null);

  const tasks = computed(() => taskStore.tasks);
  const completedTasks = computed(() => taskStore.completedTasks);

  const fetchTasks = async () => {
    loading.value = true;
    error.value = null;
    
    try {
      await taskStore.fetchTasks();
    } catch (err) {
      error.value = 'Failed to fetch tasks';
      console.error(err);
    } finally {
      loading.value = false;
    }
  };

  return {
    tasks,
    completedTasks,
    loading,
    error,
    fetchTasks
  };
}

5.4 状态管理规范

// stores/tasks.ts
import { defineStore } from 'pinia';
import { ref, computed } from 'vue';
import type { Task } from '@/types/task';

export const useTaskStore = defineStore('tasks', () => {
  // State
  const tasks = ref<Task[]>([]);
  const loading = ref(false);
  const error = ref<string | null>(null);

  // Getters
  const activeTasks = computed(() => 
    tasks.value.filter(task => !task.isCompleted)
  );

  const completedTasks = computed(() => 
    tasks.value.filter(task => task.isCompleted)
  );

  // Actions
  async function fetchTasks() {
    loading.value = true;
    try {
      const response = await fetch('/api/tasks');
      tasks.value = await response.json();
    } catch (err) {
      error.value = 'Failed to fetch tasks';
    } finally {
      loading.value = false;
    }
  }

  return {
    tasks,
    loading,
    error,
    activeTasks,
    completedTasks,
    fetchTasks
  };
});

6. API 设计规范

6.1 RESTful API 设计

// 使用名词复数形式
[HttpGet("tasks")]
public async Task<ActionResult<List<Task>>> GetTasks()
{
}

// 使用资源 ID
[HttpGet("tasks/{id}")]
public async Task<ActionResult<Task>> GetTask(int id)
{
}

// 使用 HTTP 方法表示操作
[HttpPost("tasks")]
public async Task<ActionResult<Task>> CreateTask(CreateTaskDto dto)
{
}

[HttpPut("tasks/{id}")]
public async Task<ActionResult<Task>> UpdateTask(int id, UpdateTaskDto dto)
{
}

[HttpDelete("tasks/{id}")]
public async Task<ActionResult> DeleteTask(int id)
{
}

6.2 响应格式

// 统一的响应格式
public class ApiResponse<T>
{
    public bool Success { get; set; }
    public T Data { get; set; }
    public string Message { get; set; }
    public List<string> Errors { get; set; }
}

// 成功响应
return Ok(new ApiResponse<Task>
{
    Success = true,
    Data = task,
    Message = "Task created successfully"
});

// 错误响应
return BadRequest(new ApiResponse<object>
{
    Success = false,
    Message = "Validation failed",
    Errors = new List<string> { "Title is required" }
});

7. Git 提交规范

7.1 提交信息格式

<type>(<scope>): <subject>

<body>

<footer>

7.2 Type 类型

feat: 新功能
fix: 修复 bug
docs: 文档更新
style: 代码格式调整（不影响代码运行）
refactor: 重构（既不是新功能也不是修复 bug）
perf: 性能优化
test: 测试相关
chore: 构建过程或辅助工具的变动

7.3 示例

feat(api): add task completion endpoint

- Add PATCH /api/tasks/{id}/complete endpoint
- Update task service to handle completion logic
- Add unit tests for completion functionality

Closes #123

8. 测试规范

8.1 单元测试

// 测试类命名: ClassName + Tests
public class TaskServiceTests
{
    [Fact]
    public async Task GetTasksAsync_ReturnsAllTasks()
    {
        // Arrange
        var mockRepository = new Mock<ITaskRepository>();
        var service = new TaskService(mockRepository.Object);
        
        // Act
        var result = await service.GetTasksAsync();
        
        // Assert
        Assert.NotNull(result);
        Assert.Equal(3, result.Count);
    }
}

8.2 集成测试

public class ApiIntegrationTests : IClassFixture<WebApplicationFactory<Program>>
{
    private readonly HttpClient _client;

    public ApiIntegrationTests(WebApplicationFactory<Program> factory)
    {
        _client = factory.CreateClient();
    }

    [Fact]
    public async Task GetTasks_ReturnsSuccessAndCorrectContentType()
    {
        // Act
        var response = await _client.GetAsync("/api/tasks");

        // Assert
        response.EnsureSuccessStatusCode();
        Assert.Equal("application/json", response.Content.Headers.ContentType?.MediaType);
    }
}

9. 代码审查清单

9.1 代码质量

代码符合项目规范
变量和函数命名清晰
没有重复代码
复杂逻辑有注释说明
没有硬编码的魔法数字

9.2 功能正确性

功能实现符合需求
边界条件已处理
错误处理完善
有相应的单元测试

9.3 性能和安全

没有性能问题
敏感数据已保护
输入验证完善
没有安全漏洞

10. 工具配置

10.1 C# 工具

代码格式化: dotnet format
代码分析: Roslyn Analyzers
代码风格: .editorconfig
文档生成: DocFX

10.2 JavaScript/TypeScript 工具

代码格式化: Prettier
代码检查: ESLint
类型检查: TypeScript
代码风格: .prettierrc

10.3 .editorconfig 示例

root = true

[*.cs]
indent_style = space
indent_size = 4
end_of_line = crlf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true

[*.{js,ts,vue}]
indent_style = space
indent_size = 2
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true

13 KiB Raw Permalink Blame History

Hua.Todo 代码规范文档 v1.1.0

1. 概述

2. 通用规范

2.1 命名约定

2.2 注释规范

2.3 代码格式化

3. C# 代码规范

3.1 命名规范

类和接口

方法和属性

变量和参数

常量

3.2 代码组织

文件结构

命名空间组织

3.3 编码规范

异步编程

依赖注入

异常处理

LINQ 使用

3.4 文档注释

4. JavaScript/TypeScript 代码规范

4.1 命名规范

变量和函数

类和接口

4.2 代码组织

文件结构

模块导入

4.3 TypeScript 规范

类型定义

类型断言

4.4 异步编程

5. Vue.js 代码规范

5.1 组件命名

5.2 组件结构

5.3 组合式函数规范

5.4 状态管理规范

6. API 设计规范

6.1 RESTful API 设计

6.2 响应格式

7. Git 提交规范

7.1 提交信息格式

7.2 Type 类型

7.3 示例

8. 测试规范

8.1 单元测试

8.2 集成测试

9. 代码审查清单

9.1 代码质量

9.2 功能正确性

9.3 性能和安全

10. 工具配置

10.1 C# 工具

10.2 JavaScript/TypeScript 工具

10.3 .editorconfig 示例

13 KiB

Raw Permalink Blame History