附录B - 项目结构最佳实践

// lib/main.dart
import 'package:flutter/material.dart';
import 'pages/home_page.dart';

void main() => runApp(const MyApp());

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'My App',
      theme: ThemeData(
        useMaterial3: true,
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.blue),
      ),
      home: const HomePage(),
    );
  }
}

// lib/pages/home_page.dart
import 'package:flutter/material.dart';
import '../widgets/user_card.dart';
import '../services/api_service.dart';

class HomePage extends StatefulWidget {
  const HomePage({super.key});

  @override
  State<HomePage> createState() => _HomePageState();
}

class _HomePageState extends State<HomePage> {
  final _apiService = ApiService();

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('首页')),
      body: const Center(child: Text('Hello')),
    );
  }
}

// lib/data/models/user.dart
class User {
  final int id;
  final String name;
  final String email;
  final String? avatar;

  User({
    required this.id,
    required this.name,
    required this.email,
    this.avatar,
  });

  factory User.fromJson(Map<String, dynamic> json) {
    return User(
      id: json['id'],
      name: json['name'],
      email: json['email'],
      avatar: json['avatar'],
    );
  }

  Map<String, dynamic> toJson() {
    return {
      'id': id,
      'name': name,
      'email': email,
      'avatar': avatar,
    };
  }
}

// lib/data/repositories/user_repository.dart
import '../models/user.dart';
import '../../core/network/api_client.dart';

class UserRepository {
  final ApiClient _apiClient;

  UserRepository(this._apiClient);

  // 获取用户信息
  Future<User> getUser(int id) async {
    final response = await _apiClient.get('/users/$id');
    return User.fromJson(response.data);
  }

  // 更新用户信息
  Future<User> updateUser(int id, Map<String, dynamic> data) async {
    final response = await _apiClient.put('/users/$id', data: data);
    return User.fromJson(response.data);
  }

  // 获取用户列表
  Future<List<User>> getUsers() async {
    final response = await _apiClient.get('/users');
    return (response.data as List)
        .map((json) => User.fromJson(json))
        .toList();
  }
}

// lib/providers/auth_provider.dart
import 'package:flutter/material.dart';
import '../data/models/user.dart';
import '../data/repositories/user_repository.dart';

class AuthProvider extends ChangeNotifier {
  final UserRepository _userRepository;
  
  User? _currentUser;
  bool _isLoading = false;
  String? _error;

  AuthProvider(this._userRepository);

  User? get currentUser => _currentUser;
  bool get isLoading => _isLoading;
  bool get isLoggedIn => _currentUser != null;
  String? get error => _error;

  Future<void> login(String email, String password) async {
    _isLoading = true;
    _error = null;
    notifyListeners();

    try {
      // 模拟登录逻辑
      _currentUser = await _userRepository.getUser(1);
    } catch (e) {
      _error = e.toString();
    } finally {
      _isLoading = false;
      notifyListeners();
    }
  }

  void logout() {
    _currentUser = null;
    notifyListeners();
  }
}

// lib/features/product/data/models/product.dart
class Product {
  final int id;
  final String name;
  final String description;
  final double price;
  final String imageUrl;
  final int stock;

  Product({
    required this.id,
    required this.name,
    required this.description,
    required this.price,
    required this.imageUrl,
    required this.stock,
  });

  factory Product.fromJson(Map<String, dynamic> json) {
    return Product(
      id: json['id'],
      name: json['name'],
      description: json['description'],
      price: (json['price'] as num).toDouble(),
      imageUrl: json['image_url'],
      stock: json['stock'],
    );
  }

  bool get isInStock => stock > 0;
}

// lib/features/product/data/repositories/product_repository.dart
import '../models/product.dart';
import '../../../../core/network/api_client.dart';

abstract class ProductRepository {
  Future<List<Product>> getProducts();
  Future<Product> getProductById(int id);
  Future<List<Product>> searchProducts(String query);
}

class ProductRepositoryImpl implements ProductRepository {
  final ApiClient _apiClient;

  ProductRepositoryImpl(this._apiClient);

  @override
  Future<List<Product>> getProducts() async {
    final response = await _apiClient.get('/products');
    return (response.data as List)
        .map((json) => Product.fromJson(json))
        .toList();
  }

  @override
  Future<Product> getProductById(int id) async {
    final response = await _apiClient.get('/products/$id');
    return Product.fromJson(response.data);
  }

  @override
  Future<List<Product>> searchProducts(String query) async {
    final response = await _apiClient.get('/products/search', 
      queryParameters: {'q': query},
    );
    return (response.data as List)
        .map((json) => Product.fromJson(json))
        .toList();
  }
}

// lib/features/product/presentation/providers/product_provider.dart
import 'package:flutter/material.dart';
import '../../data/models/product.dart';
import '../../data/repositories/product_repository.dart';

class ProductProvider extends ChangeNotifier {
  final ProductRepository _repository;

  ProductProvider(this._repository);

  List<Product> _products = [];
  Product? _selectedProduct;
  bool _isLoading = false;
  String? _error;

  List<Product> get products => _products;
  Product? get selectedProduct => _selectedProduct;
  bool get isLoading => _isLoading;
  String? get error => _error;

  Future<void> loadProducts() async {
    _isLoading = true;
    _error = null;
    notifyListeners();

    try {
      _products = await _repository.getProducts();
    } catch (e) {
      _error = '加载商品失败：$e';
    } finally {
      _isLoading = false;
      notifyListeners();
    }
  }

  Future<void> loadProductDetail(int id) async {
    _isLoading = true;
    _error = null;
    notifyListeners();

    try {
      _selectedProduct = await _repository.getProductById(id);
    } catch (e) {
      _error = '加载商品详情失败：$e';
    } finally {
      _isLoading = false;
      notifyListeners();
    }
  }

  Future<void> searchProducts(String query) async {
    if (query.isEmpty) {
      await loadProducts();
      return;
    }

    _isLoading = true;
    _error = null;
    notifyListeners();

    try {
      _products = await _repository.searchProducts(query);
    } catch (e) {
      _error = '搜索失败：$e';
    } finally {
      _isLoading = false;
      notifyListeners();
    }
  }
}

// lib/features/product/presentation/pages/product_list_page.dart
import 'package:flutter/material.dart';
import 'package:provider/provider.dart';
import '../providers/product_provider.dart';
import '../widgets/product_card.dart';

class ProductListPage extends StatefulWidget {
  const ProductListPage({super.key});

  @override
  State<ProductListPage> createState() => _ProductListPageState();
}

class _ProductListPageState extends State<ProductListPage> {
  @override
  void initState() {
    super.initState();
    // 加载商品列表
    Future.microtask(() {
      context.read<ProductProvider>().loadProducts();
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('商品列表')),
      body: Consumer<ProductProvider>(
        builder: (context, provider, child) {
          if (provider.isLoading) {
            return const Center(child: CircularProgressIndicator());
          }

          if (provider.error != null) {
            return Center(
              child: Column(
                mainAxisAlignment: MainAxisAlignment.center,
                children: [
                  Text(provider.error!),
                  const SizedBox(height: 16),
                  ElevatedButton(
                    onPressed: () => provider.loadProducts(),
                    child: const Text('重试'),
                  ),
                ],
              ),
            );
          }

          return GridView.builder(
            padding: const EdgeInsets.all(16),
            gridDelegate: const SliverGridDelegateWithFixedCrossAxisCount(
              crossAxisCount: 2,
              childAspectRatio: 0.75,
              crossAxisSpacing: 16,
              mainAxisSpacing: 16,
            ),
            itemCount: provider.products.length,
            itemBuilder: (context, index) {
              return ProductCard(product: provider.products[index]);
            },
          );
        },
      ),
    );
  }
}

// models/user.dart
class User {
  final String name;
  final String email;
  
  User({required this.name, required this.email});
}

// controllers/user_controller.dart
class UserController {
  User? _user;
  
  User? get user => _user;
  
  Future<void> loadUser() async {
    // 加载用户数据
    _user = User(name: '张三', email: 'zhangsan@example.com');
  }
  
  void updateName(String name) {
    if (_user != null) {
      _user = User(name: name, email: _user!.email);
    }
  }
}

// views/user_page.dart
class UserPage extends StatefulWidget {
  @override
  State<UserPage> createState() => _UserPageState();
}

class _UserPageState extends State<UserPage> {
  final _controller = UserController();
  
  @override
  void initState() {
    super.initState();
    _loadData();
  }
  
  Future<void> _loadData() async {
    await _controller.loadUser();
    setState(() {});
  }
  
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: Text(_controller.user?.name ?? '加载中...'),
      ),
    );
  }
}

// models/todo.dart
class Todo {
  final int id;
  final String title;
  final bool completed;
  
  Todo({
    required this.id,
    required this.title,
    this.completed = false,
  });
  
  Todo copyWith({String? title, bool? completed}) {
    return Todo(
      id: id,
      title: title ?? this.title,
      completed: completed ?? this.completed,
    );
  }
}

// services/todo_service.dart
class TodoService {
  Future<List<Todo>> fetchTodos() async {
    // 模拟 API 请求
    await Future.delayed(const Duration(seconds: 1));
    return [
      Todo(id: 1, title: '学习 Flutter'),
      Todo(id: 2, title: '写代码'),
      Todo(id: 3, title: '看文档'),
    ];
  }
}

// viewmodels/todo_viewmodel.dart
import 'package:flutter/material.dart';

class TodoViewModel extends ChangeNotifier {
  final TodoService _service;
  
  List<Todo> _todos = [];
  bool _isLoading = false;
  
  TodoViewModel(this._service);
  
  List<Todo> get todos => _todos;
  bool get isLoading => _isLoading;
  int get completedCount => _todos.where((t) => t.completed).length;
  
  Future<void> loadTodos() async {
    _isLoading = true;
    notifyListeners();
    
    _todos = await _service.fetchTodos();
    
    _isLoading = false;
    notifyListeners();
  }
  
  void toggleTodo(int id) {
    final index = _todos.indexWhere((t) => t.id == id);
    if (index != -1) {
      _todos[index] = _todos[index].copyWith(
        completed: !_todos[index].completed,
      );
      notifyListeners();
    }
  }
  
  void addTodo(String title) {
    final newTodo = Todo(
      id: DateTime.now().millisecondsSinceEpoch,
      title: title,
    );
    _todos.add(newTodo);
    notifyListeners();
  }
}

// views/todo_page.dart
class TodoPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return ChangeNotifierProvider(
      create: (_) => TodoViewModel(TodoService())..loadTodos(),
      child: const _TodoPageContent(),
    );
  }
}

class _TodoPageContent extends StatelessWidget {
  const _TodoPageContent();

  @override
  Widget build(BuildContext context) {
    final viewModel = context.watch<TodoViewModel>();
    
    return Scaffold(
      appBar: AppBar(
        title: Text('待办事项 (${viewModel.completedCount}/${viewModel.todos.length})'),
      ),
      body: viewModel.isLoading
          ? const Center(child: CircularProgressIndicator())
          : ListView.builder(
              itemCount: viewModel.todos.length,
              itemBuilder: (context, index) {
                final todo = viewModel.todos[index];
                return CheckboxListTile(
                  title: Text(
                    todo.title,
                    style: TextStyle(
                      decoration: todo.completed
                          ? TextDecoration.lineThrough
                          : null,
                    ),
                  ),
                  value: todo.completed,
                  onChanged: (_) => viewModel.toggleTodo(todo.id),
                );
              },
            ),
    );
  }
}

// domain/entities/user.dart（实体 - 纯业务对象）
class User {
  final int id;
  final String name;
  final String email;

  const User({
    required this.id,
    required this.name,
    required this.email,
  });
}

// domain/repositories/user_repository.dart（仓库接口）
abstract class UserRepository {
  Future<User> getUser(int id);
  Future<void> updateUser(User user);
}

// domain/usecases/get_user.dart（用例 - 业务逻辑）
class GetUser {
  final UserRepository repository;

  GetUser(this.repository);

  Future<User> call(int id) async {
    return await repository.getUser(id);
  }
}

// data/models/user_model.dart（数据模型 - 带序列化）
class UserModel extends User {
  const UserModel({
    required super.id,
    required super.name,
    required super.email,
  });

  factory UserModel.fromJson(Map<String, dynamic> json) {
    return UserModel(
      id: json['id'],
      name: json['name'],
      email: json['email'],
    );
  }

  Map<String, dynamic> toJson() {
    return {'id': id, 'name': name, 'email': email};
  }
}

// data/datasources/user_remote_datasource.dart
abstract class UserRemoteDataSource {
  Future<UserModel> getUser(int id);
}

class UserRemoteDataSourceImpl implements UserRemoteDataSource {
  final ApiClient client;

  UserRemoteDataSourceImpl(this.client);

  @override
  Future<UserModel> getUser(int id) async {
    final response = await client.get('/users/$id');
    return UserModel.fromJson(response.data);
  }
}

// data/repositories/user_repository_impl.dart（仓库实现）
class UserRepositoryImpl implements UserRepository {
  final UserRemoteDataSource remoteDataSource;
  final UserLocalDataSource localDataSource;

  UserRepositoryImpl({
    required this.remoteDataSource,
    required this.localDataSource,
  });

  @override
  Future<User> getUser(int id) async {
    try {
      // 优先从网络获取
      final user = await remoteDataSource.getUser(id);
      // 缓存到本地
      await localDataSource.cacheUser(user);
      return user;
    } catch (e) {
      // 网络失败，从本地获取
      return await localDataSource.getUser(id);
    }
  }

  @override
  Future<void> updateUser(User user) async {
    // 实现更新逻辑
  }
}

// ✅ 正确
class UserProfile {}
class ApiService {}
class CustomButton extends StatelessWidget {}

// ❌ 错误
class userProfile {}
class api_service {}

// ✅ 正确
String userName = 'Tom';
void loadUserData() {}
final isLoading = false;

// ❌ 错误
String user_name = 'Tom';
void LoadUserData() {}

// ✅ 两种风格都可以
const int maxRetryCount = 3;
const int MAX_RETRY_COUNT = 3;

const String apiBaseUrl = 'https://api.example.com';
const String API_BASE_URL = 'https://api.example.com';

class UserService {
  // 私有变量
  final String _apiKey;
  
  // 私有方法
  void _validateInput() {}
  
  // 公开方法
  Future<void> loadUser() async {}
}

// 1. Dart SDK
import 'dart:async';
import 'dart:convert';

// 2. Flutter SDK
import 'package:flutter/material.dart';
import 'package:flutter/services.dart';

// 3. 第三方包
import 'package:dio/dio.dart';
import 'package:provider/provider.dart';

// 4. 项目内部包
import 'package:my_app/core/utils.dart';
import 'package:my_app/models/user.dart';

// 5. 相对路径导入
import '../widgets/custom_button.dart';
import './user_card.dart';

// 1. 导入
import 'package:flutter/material.dart';

// 2. 常量
const double _kDefaultPadding = 16.0;

// 3. 枚举
enum UserStatus { active, inactive, pending }

// 4. 类定义
class UserPage extends StatefulWidget {
  // 4.1 静态常量
  static const routeName = '/user';
  
  // 4.2 成员变量
  final int userId;
  
  // 4.3 构造函数
  const UserPage({super.key, required this.userId});
  
  // 4.4 方法
  @override
  State<UserPage> createState() => _UserPageState();
}

class _UserPageState extends State<UserPage> {
  // 4.1 成员变量
  bool _isLoading = false;
  
  // 4.2 生命周期方法
  @override
  void initState() {
    super.initState();
    _loadData();
  }
  
  @override
  void dispose() {
    super.dispose();
  }
  
  // 4.3 私有方法
  Future<void> _loadData() async {}
  
  // 4.4 build 方法
  @override
  Widget build(BuildContext context) {
    return Scaffold();
  }
}

// 5. 辅助函数
String formatUserName(String name) => name.trim();

// ❌ 错误：把所有逻辑写在 UI 中
class BadPage extends StatefulWidget {
  @override
  Widget build(BuildContext context) {
    // 直接在这里调用 API、处理数据...
  }
}

// ✅ 正确：分离业务逻辑
class GoodPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Consumer<UserProvider>(
      builder: (context, provider, child) {
        // UI 只负责展示
      },
    );
  }
}

// ❌ 错误：超大文件（>500行）
// 一个文件包含多个类和大量逻辑

// ✅ 正确：拆分文件
// user_page.dart - 页面
// user_provider.dart - 状态管理
// user_widgets.dart - 子组件