Skip to content

development_environment_setup.md

Latest commit

 

History

History
396 lines (299 loc) · 11.4 KB

development_environment_setup.md

File metadata and controls

396 lines (299 loc) · 11.4 KB
Raw

1Panel 移动端APP - 开发环境设置文档

1. 概述

本文档提供了1Panel移动端APP开发环境的详细设置指南，帮助开发人员快速搭建开发环境并开始工作。同时，本文档也包含了开发标准和规范，以确保代码质量和可维护性，避免"屎山代码"的堆积。

2. 系统要求

2.1 硬件要求

  • 操作系统：Windows 10/11、macOS 12+、Linux (Ubuntu 20.04+)
  • 处理器：Intel Core i5 或更高配置
  • 内存：8GB RAM 或更高
  • 存储空间：至少 10GB 可用空间
  • 网络连接：稳定的互联网连接

2.2 软件要求

  • Flutter SDK：3.16+（推荐最新稳定版）
  • Dart SDK：3.2+（与Flutter SDK捆绑）
  • Android Studio：最新稳定版（用于Android开发）
  • Xcode：14.0+（macOS上，用于iOS开发）
  • Visual Studio Code：最新稳定版（推荐的代码编辑器）
  • Git：最新稳定版

3. 安装Flutter SDK

3.1 Windows安装步骤

  1. 访问 Flutter官网下载页面 下载最新的Flutter SDK压缩包
  2. 解压Flutter SDK到你选择的目录（例如 C:\src\flutter）
  3. 将Flutter的bin目录添加到系统环境变量PATH中
  4. 打开命令提示符或PowerShell，运行以下命令以验证安装： 
    flutter doctor

3.2 macOS安装步骤

  1. 访问 Flutter官网下载页面 下载最新的Flutter SDK压缩包
  2. 解压Flutter SDK到你选择的目录（例如 ~/development/flutter）
  3. 将Flutter的bin目录添加到PATH中： 
    echo "export PATH=\$PATH:\$HOME/development/flutter/bin" >> ~/.zshrc
source ~/.zshrc
  4. 打开终端，运行以下命令以验证安装： 
    flutter doctor

3.3 Linux安装步骤

  1. 访问 Flutter官网下载页面 下载最新的Flutter SDK压缩包
  2. 解压Flutter SDK到你选择的目录（例如 ~/development/flutter）
  3. 将Flutter的bin目录添加到PATH中： 
    echo "export PATH=\$PATH:\$HOME/development/flutter/bin" >> ~/.bashrc
source ~/.bashrc
  4. 打开终端，运行以下命令以验证安装： 
    flutter doctor

4. 安装Android开发工具

4.1 安装Android Studio

  1. 访问 Android Studio官网 下载并安装最新版本的Android Studio
  2. 启动Android Studio，并按照安装向导的指示完成设置
  3. 在Android Studio中安装Android SDK、Android SDK Platform-Tools和Android SDK Build-Tools
  4. 配置Android SDK环境变量：
    • Windows: 设置ANDROID_SDK_ROOT环境变量指向Android SDK的安装路径
    • macOS/Linux: 在shell配置文件中添加export ANDROID_SDK_ROOT=$HOME/Android/Sdk

4.2 配置Android虚拟设备 (AVD)

  1. 在Android Studio中，点击"Tools" > "AVD Manager"
  2. 点击"Create Virtual Device..."
  3. 选择一个设备定义（推荐使用"Pixel 5"或更高版本）
  4. 选择一个系统镜像（推荐使用最新的稳定版Android系统）
  5. 完成虚拟设备的创建和配置

5. 安装iOS开发工具 (仅macOS)

5.1 安装Xcode

  1. 从Mac App Store下载并安装最新版本的Xcode
  2. 打开Xcode，按照提示完成初始设置
  3. 安装Xcode命令行工具： 
    xcode-select --install

5.2 配置iOS模拟器

  1. 在Xcode中，点击"Xcode" > "Preferences" > "Components"
  2. 选择并安装最新的iOS模拟器
  3. 打开模拟器：open -a Simulator

6. 安装Visual Studio Code

  1. 访问 Visual Studio Code官网 下载并安装最新版本的VS Code
  2. 打开VS Code，安装以下推荐的扩展：
    • Flutter（由Dart Code提供）
    • Dart（由Dart Code提供）
    • Material Icon Theme
    • GitLens
    • Bracket Pair Colorizer

7. 安装Git

  1. 访问 Git官网 下载并安装最新版本的Git
  2. 配置Git用户名和邮箱： 
    git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

8. 克隆项目代码

  1. 打开命令行工具（命令提示符/PowerShell/终端）
  2. 导航到你想要存储项目的目录
  3. 运行以下命令克隆项目代码： 
    git clone <repository-url>
cd onepanelapp_app

9. 安装项目依赖

  1. 在项目根目录中，运行以下命令安装Flutter依赖： 
    flutter pub get
  2. 运行以下命令安装代码生成工具： 
    flutter pub run build_runner build --delete-conflicting-outputs

10. 配置开发环境

10.1 API配置

  1. 在项目根目录创建一个.env文件
  2. 添加以下配置（根据你的环境修改）： 
    API_BASE_URL=https://your-1panel-server.com
DEBUG_MODE=true

10.2 IDE配置

  1. 在VS Code中打开项目
  2. 配置调试器：点击"Run" > "Add Configuration" > 选择"Dart & Flutter"
  3. 更新launch.json文件以包含正确的配置

11. 运行项目

11.1 在Android模拟器/设备上运行

  1. 确保Android模拟器正在运行或已连接Android设备
  2. 在VS Code中，按F5或点击"Run" > "Start Debugging"
  3. 或者在命令行中运行： 
    flutter run

11.2 在iOS模拟器/设备上运行 (仅macOS)

  1. 确保iOS模拟器正在运行或已连接iOS设备
  2. 在VS Code中，按F5或点击"Run" > "Start Debugging"
  3. 或者在命令行中运行： 
    flutter run

12. 开发工具和技巧

12.1 Flutter DevTools

Flutter提供了一组强大的开发工具，用于调试、性能分析和UI检查：

  1. 在命令行中运行： 
    flutter pub global activate devtools
  2. 启动应用后，运行： 
    flutter pub global run devtools
  3. 在浏览器中打开提供的URL

12.2 常用Flutter命令

# 检查Flutter环境
flutter doctor

# 获取依赖
flutter pub get

# 运行应用
flutter run

# 热重载（在应用运行时按r键）
r

# 热重启（在应用运行时按R键）
R

# 构建APK
flutter build apk

# 构建iOS应用
flutter build ios

# 运行测试
flutter test

# 生成代码
flutter pub run build_runner build

13. 常见问题解决

13.1 Android许可证问题

如果运行flutter doctor时出现Android许可证问题：

flutter doctor --android-licenses

按照提示接受所有许可证。

13.2 依赖冲突问题

如果遇到依赖冲突：

flutter pub upgrade

或删除pubspec.lock文件后重新运行flutter pub get。

13.3 Xcode版本不兼容问题

如果Xcode版本不兼容：

  1. 更新到最新版本的Xcode
  2. 或在Podfile中指定兼容的iOS版本

13.4 模拟器启动缓慢问题

如果Android模拟器启动缓慢，可以启用GPU加速或使用物理设备进行开发。

14. 开发标准与规范

为确保项目的代码质量、可维护性和可扩展性，所有开发人员必须严格遵守以下开发标准和规范。

14.1 代码规范

14.1.1 Dart语言规范

  • 遵循Dart官方风格指南
  • 使用2个空格进行缩进
  • 每行不超过100个字符
  • 使用小驼峰命名变量和函数（如userName、getUserData()）
  • 使用大驼峰命名类和枚举（如UserModel、AuthService）
  • 使用下划线前缀标识私有成员（如_privateVar、_privateMethod()）
  • 导入顺序：Dart核心库、Flutter库、第三方库、项目内部库
  • 使用空安全（null safety）特性
  • 避免使用dynamic类型

14.1.2 Flutter组件规范

  • 组件命名使用大驼峰（如UserProfileCard）
  • 组件应保持单一职责
  • 使用const构造函数创建无状态组件
  • 避免在build方法中执行复杂计算
  • 使用const修饰符优化性能
  • 组件应具备可复用性和可测试性
  • 优先使用组合而非继承

14.2 架构设计

14.2.1 整体架构

  • 采用MVVM（Model-View-ViewModel）或Clean Architecture架构模式
  • 分离UI逻辑和业务逻辑
  • 使用依赖注入管理对象创建和依赖关系
  • 实现数据层与UI层的松耦合

14.2.2 目录结构

  • lib/：主源代码目录
    • src/：应用源代码
      • models/：数据模型
      • services/：服务类（API调用、数据处理等）
      • viewmodels/：视图模型（处理UI逻辑和状态）
      • views/：UI组件和页面
      • widgets/：可复用UI组件
      • utils/：工具函数和辅助类
      • constants/：常量定义
      • routes/：路由配置
      • themes/：主题和样式
      • localization/：国际化资源
    • main.dart：应用入口文件

14.3 状态管理

  • 优先使用Flutter内置的状态管理（setState、InheritedWidget）
  • 对于复杂状态，使用Provider、Riverpod或Bloc
  • 避免在Widget之间直接传递状态
  • 状态应尽可能在最低需要它的层级上管理
  • 对于全局状态，考虑使用单例或全局状态管理器

14.4 错误处理

  • 统一的错误处理机制
  • 使用try-catch捕获可能的异常
  • 为网络请求添加超时处理
  • 向用户显示友好的错误信息
  • 记录详细的错误日志，包括时间、操作、错误类型和堆栈跟踪
  • 实现崩溃报告机制

14.5 日志记录

  • 使用统一的日志工具（如logger包）
  • 分级日志：调试、信息、警告、错误、严重错误
  • 在开发环境显示详细日志，生产环境只记录关键信息
  • 避免在日志中包含敏感信息（如密码、令牌等）
  • 实现日志文件存储，便于问题排查

14.6 性能优化

  • 优化Widget重建
  • 使用const构造函数
  • 实现懒加载和分页加载
  • 优化网络请求（缓存、压缩、批量请求）
  • 合理使用FutureBuilder和StreamBuilder
  • 避免内存泄漏（正确处理流订阅、定时器等）
  • 使用Flutter DevTools进行性能分析

14.7 安全性

  • 安全存储敏感信息（使用flutter_secure_storage）
  • 避免硬编码凭证
  • 实现HTTPS通信
  • 定期刷新认证令牌
  • 验证所有用户输入
  • 防止SQL注入和XSS攻击
  • 实现数据加密存储

15. 团队协作流程

15.1 Git工作流

  1. 创建新分支进行开发： 
    git checkout -b feature/your-feature-name
  2. 提交更改： 
    git add .
git commit -m "Add feature description"
  3. 推送到远程仓库： 
    git push origin feature/your-feature-name
  4. 创建Pull Request进行代码审查

15.2 代码审查流程

  1. 所有代码更改必须通过Pull Request
  2. 至少需要一位团队成员批准才能合并
  3. 确保所有测试通过
  4. 遵循项目的代码规范
  5. 关注代码质量、性能和安全性
  6. 提供具体的反馈和改进建议

15.3 文档规范

  • 为所有公共API编写文档注释
  • 代码注释应解释为什么这样做，而不是做了什么
  • 为复杂的业务逻辑提供流程图或说明
  • 定期更新API文档和用户文档
  • 确保文档与代码保持同步

15. 后续步骤

  1. 阅读项目文档，了解项目架构和设计
  2. 熟悉1Panel API文档
  3. 开始实现功能或修复Bug
  4. 定期更新Flutter SDK和依赖

通过遵循本指南，您应该能够成功设置1Panel移动端APP的开发环境并开始开发工作。如果您遇到任何问题，请参考Flutter官方文档或联系团队成员寻求帮助。