shop-wx/doc/examples/README.md

# 代码示例

本目录包含了项目代码编写规范的完整示例，展示了项目中各种场景下的最佳实践。

## 文件说明

### 1. api-example.ts
**API 接口示例代码**

展示了：
- 如何组织和编写 API 接口
- TypeScript 类型定义的规范
- 接口注释的写法
- API 函数命名规范
- 返回数据处理的最佳实践

**关键要点：**
- 按业务模块分组 API
- 为每个 API 函数添加详细的中文注释
- 使用 TypeScript 类型约束参数和返回值
- 统一检查响应状态并处理错误

### 2. page-example.vue
**页面组件示例代码**

展示了：
- Vue 3 Composition API 的使用方式
- 页面结构的标准写法
- 响应式数据的定义
- 事件的处理方式
- 样式组织规范

**关键要点：**
- 使用 `<script lang="ts" setup>` 语法
- 按框架 -> 第三方 -> 工具 -> 本地模块的顺序导入
- 使用 `definePage` 配置页面
- 合理组织模板和样式

### 3. component-example.vue
**组件开发示例代码**

展示了：
- 组件 Props 的定义方式
- 组件 Emits 的类型约束
- 默认值的设置
- 组件的封装和复用

**关键要点：**
- 使用 `withDefaults` 提供 Props 默认值
- 使用 `defineEmits` 定义事件类型
- 遵循单一职责原则
- 保持组件的可复用性

### 4. store-example.ts
**状态管理示例代码（Pinia）**

展示了：
- 使用 Composition API 风格定义 Store
- 状态和计算属性的写法
- 异步操作的封装
- 状态管理的方法组织

**关键要点：**
- 使用 `defineStore` 创建 store
- 使用 `ref` 声明状态
- 使用 `computed` 定义计算属性
- 合理组织同步和异步操作

### 5. utils-example.ts
**工具函数示例代码**

展示了：
- 工具函数的封装方式
- JSDoc 注释的写法
- 函数的类型约束
- 通用功能的抽象

**关键要点：**
- 使用 JSDoc 格式添加详细注释
- 为函数参数和返回值添加类型约束
- 处理边界情况和异常
- 保持函数的纯度（无副作用）

## 使用指南

### 1. 学习方式
建议按照以下顺序学习示例代码：
1. 先阅读 `代码编写规范.md` 了解整体规范
2. 查看 `api-example.ts` 了解 API 设计
3. 学习 `store-example.ts` 掌握状态管理
4. 学习 `utils-example.ts` 掌握工具函数
5. 最后学习 `page-example.vue` 和 `component-example.vue` 了解页面和组件开发

### 2. 实践建议
- 复制示例代码到实际项目中进行修改测试
- 尝试修改示例代码，添加新功能
- 对比自己的代码和示例代码的差异
- 将示例代码的模式应用到实际项目中

### 3. 注意事项
- 示例代码仅供参考，请根据实际项目需求调整
- 不要直接复制粘贴，要理解其原理和思路
- 在实际项目中要考虑业务逻辑的特殊性
- 保持代码风格的一致性

## 示例代码目录结构

```
examples/
├── README.md           # 本文件
├── api-example.ts      # API 示例
├── page-example.vue    # 页面示例
├── component-example.vue # 组件示例
├── store-example.ts    # 状态管理示例
└── utils-example.ts    # 工具函数示例
```

## 代码风格对比

### ✅ 推荐的写法

```typescript
/**
 * 获取用户列表
 * @param params 搜索参数
 * @param params.keyword 搜索关键词
 * @returns 用户列表
 */
export function getUserList(params?: UserParams) {
  return http.get<User[]>('/api/users', params);
}
```

```vue
<script lang="ts" setup>
import { ref, onMounted } from 'vue';
import { getData } from '@/api/example';

const loading = ref(false);
const data = ref([]);

const fetchData = async () => {
  loading.value = true;
  try {
    data.value = await getData();
  } finally {
    loading.value = false;
  }
};

onMounted(() => {
  fetchData();
});
</script>
```

```typescript
import { defineStore } from 'pinia';
import { ref } from 'vue';
import { getData } from '@/api/example';

export const useExampleStore = defineStore('example', () => {
  const data = ref([]);
  const loading = ref(false);

  const fetchData = async () => {
    loading.value = true;
    try {
      data.value = await getData();
    } finally {
      loading.value = false;
    }
  };

  return {
    data,
    loading,
    fetchData,
  };
});
```

### ❌ 不推荐的写法

```typescript
// 错误示例：没有注释
export function getUsers(params?: any) {
  return http.get('/api/users', params);
}

// 错误示例：命名不规范
export function users_list() {
  return http.get('/api/users');
}

// 错误示例：没有类型约束
export function createUser(data: any) {
  return http.post('/api/users', data);
}
```

```vue
<script>
// 错误示例：没有使用 TypeScript
export default {
  data() {
    return {
      loading: false,
      data: [],
    };
  },
  mounted() {
    this.fetchData();
  },
  methods: {
    fetchData() {
      // 实现...
    },
  },
};
</script>
```

```typescript
// 错误示例：使用 Options API 风格
export const useExampleStore = defineStore('example', {
  state: () => ({
    data: [],
    loading: false,
  }),
  actions: {
    async fetchData() {
      this.loading = true;
      try {
        this.data = await getData();
      } finally {
        this.loading = false;
      }
    },
  },
});
```

## 扩展阅读

1. [Vue 3 官方文档](https://cn.vuejs.org/)
2. [TypeScript 官方文档](https://www.typescriptlang.org/)
3. [Pinia 官方文档](https://pinia.vuejs.org/)
4. [uni-app 官方文档](https://uniapp.dcloud.net.cn/)

## 更新日志

### v1.0.0 (2025-10-29)
- 初始版本
- 添加 API 示例代码
- 添加页面示例代码
- 添加组件示例代码
- 添加状态管理示例代码
- 添加工具函数示例代码

---

> **提示**：这些示例代码基于项目的实际代码风格编写，遵循了项目的代码规范和最佳实践。在实际开发中，请根据具体需求调整和优化。