doc:整理文档
This commit is contained in:
ShaoHua
@@ -0,0 +1,675 @@
|
||||
# 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 命名规范
|
||||
|
||||
#### 类和接口
|
||||
```csharp
|
||||
// 类名使用 PascalCase
|
||||
public class TaskService
|
||||
{
|
||||
}
|
||||
|
||||
// 接口名使用 PascalCase，以 I 开头
|
||||
public interface ITaskService
|
||||
{
|
||||
}
|
||||
```
|
||||
|
||||
#### 方法和属性
|
||||
```csharp
|
||||
// 方法名使用 PascalCase
|
||||
public Task<List<Task>> GetTasksAsync()
|
||||
{
|
||||
}
|
||||
|
||||
// 属性名使用 PascalCase
|
||||
public string Title { get; set; }
|
||||
```
|
||||
|
||||
#### 变量和参数
|
||||
```csharp
|
||||
// 私有字段使用 _camelCase
|
||||
private readonly ITaskRepository _taskRepository;
|
||||
|
||||
// 局部变量使用 camelCase
|
||||
var taskList = await GetTasksAsync();
|
||||
|
||||
// 方法参数使用 camelCase
|
||||
public void CreateTask(string title, TaskPriority priority)
|
||||
{
|
||||
}
|
||||
```
|
||||
|
||||
#### 常量
|
||||
```csharp
|
||||
// 常量使用 PascalCase
|
||||
public const int MaxTaskTitleLength = 200;
|
||||
```
|
||||
|
||||
### 3.2 代码组织
|
||||
|
||||
#### 文件结构
|
||||
```csharp
|
||||
// 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 编码规范
|
||||
|
||||
#### 异步编程
|
||||
```csharp
|
||||
// 异步方法应以 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);
|
||||
}
|
||||
```
|
||||
|
||||
#### 依赖注入
|
||||
```csharp
|
||||
// 优先使用构造函数注入
|
||||
public class TaskService : ITaskService
|
||||
{
|
||||
private readonly ITaskRepository _taskRepository;
|
||||
private readonly ILogger<TaskService> _logger;
|
||||
|
||||
public TaskService(ITaskRepository taskRepository, ILogger<TaskService> logger)
|
||||
{
|
||||
_taskRepository = taskRepository;
|
||||
_logger = logger;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 异常处理
|
||||
```csharp
|
||||
// 使用具体的异常类型
|
||||
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 使用
|
||||
```csharp
|
||||
// 优先使用方法语法
|
||||
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 文档注释
|
||||
```csharp
|
||||
/// <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 命名规范
|
||||
|
||||
#### 变量和函数
|
||||
```typescript
|
||||
// 变量使用 camelCase
|
||||
const taskList = [];
|
||||
let currentTask = null;
|
||||
|
||||
// 函数使用 camelCase
|
||||
function getTasks() {
|
||||
// 实现
|
||||
}
|
||||
|
||||
// 常量使用 UPPER_SNAKE_CASE
|
||||
const MAX_TASK_TITLE_LENGTH = 200;
|
||||
```
|
||||
|
||||
#### 类和接口
|
||||
```typescript
|
||||
// 类名使用 PascalCase
|
||||
class TaskService {
|
||||
// 实现
|
||||
}
|
||||
|
||||
// 接口名使用 PascalCase
|
||||
interface Task {
|
||||
id: number;
|
||||
title: string;
|
||||
}
|
||||
|
||||
// 类型别名使用 PascalCase
|
||||
type TaskPriority = 'high' | 'medium' | 'low';
|
||||
```
|
||||
|
||||
### 4.2 代码组织
|
||||
|
||||
#### 文件结构
|
||||
```typescript
|
||||
// 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() {
|
||||
// 实现
|
||||
}
|
||||
```
|
||||
|
||||
#### 模块导入
|
||||
```typescript
|
||||
// 优先使用 ES6 模块语法
|
||||
import { ref } from 'vue';
|
||||
import axios from 'axios';
|
||||
|
||||
// 导出使用具名导出
|
||||
export function useTasks() {
|
||||
// 实现
|
||||
}
|
||||
|
||||
export default useTasks;
|
||||
```
|
||||
|
||||
### 4.3 TypeScript 规范
|
||||
|
||||
#### 类型定义
|
||||
```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;
|
||||
}
|
||||
```
|
||||
|
||||
#### 类型断言
|
||||
```typescript
|
||||
// 优先使用类型守卫而非类型断言
|
||||
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 异步编程
|
||||
```typescript
|
||||
// 使用 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 组件命名
|
||||
```vue
|
||||
<!-- 组件名使用 PascalCase -->
|
||||
<script setup lang="ts">
|
||||
// 组件名应与文件名一致
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<!-- 模板中使用 kebab-case -->
|
||||
<task-item :task="task" />
|
||||
</template>
|
||||
```
|
||||
|
||||
### 5.2 组件结构
|
||||
```vue
|
||||
<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 组合式函数规范
|
||||
```typescript
|
||||
// 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 状态管理规范
|
||||
```typescript
|
||||
// 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 设计
|
||||
```csharp
|
||||
// 使用名词复数形式
|
||||
[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 响应格式
|
||||
```csharp
|
||||
// 统一的响应格式
|
||||
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 单元测试
|
||||
```csharp
|
||||
// 测试类命名: 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 集成测试
|
||||
```csharp
|
||||
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 示例
|
||||
```ini
|
||||
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
|
||||
```
|
||||
Reference in New Issue
Block a user