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    # 工具函数示例

代码风格对比

✅ 推荐的写法

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

<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>

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,
  };
});

❌ 不推荐的写法

// 错误示例：没有注释
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);
}

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

// 错误示例：使用 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 官方文档
2. TypeScript 官方文档
3. Pinia 官方文档
4. uni-app 官方文档

更新日志

v1.0.0 (2025-10-29)

• 初始版本
• 添加 API 示例代码
• 添加页面示例代码
• 添加组件示例代码
• 添加状态管理示例代码
• 添加工具函数示例代码

---

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