Flutter Flavors & Multiple Environments

      Trong quá trình phát triển một ứng dụng di động bằng Flutter, nhóm phát triển thường phải làm việc với nhiều môi trường khác nhau như Development, Staging, QA và Production. Mỗi môi trường có thể sử dụng một API endpoint riêng, cơ sở dữ liệu riêng, tên ứng dụng riêng, biểu tượng riêng hoặc các tính năng được bật/tắt khác nhau. Nếu tất cả cấu hình được viết cứng trong mã nguồn, việc chuyển đổi giữa các môi trường sẽ trở nên thủ công, dễ sai sót và khó kiểm soát.

Flutter cung cấp cơ chế Flavors, kết hợp với các tệp cấu hình và biến môi trường, để giải quyết vấn đề này. Flavors cho phép tạo ra nhiều phiên bản của cùng một ứng dụng từ một codebase duy nhất. Nhờ đó, nhóm phát triển có thể xây dựng và phân phối các bản Development, Staging hoặc Production với cấu hình phù hợp mà không cần sao chép dự án.

Flutter Flavors không chỉ là một tính năng hỗ trợ build ứng dụng. Đây còn là một phương pháp tổ chức quy trình phát triển, kiểm thử và phát hành phần mềm một cách chuyên nghiệp, an toàn và có khả năng mở rộng.

1. Khái niệm Multiple Environments

1.1. Multiple Environments là gì?

Multiple Environments, hay nhiều môi trường triển khai, là cách tổ chức hệ thống thành các phiên bản có mục đích sử dụng khác nhau. Trong một dự án Flutter phổ biến, ta thường có các môi trường sau:

Development: Dành cho lập trình viên phát triển tính năng mới và kiểm tra nhanh trên máy cá nhân.
Testing hoặc QA: Dành cho nhóm kiểm thử xác minh chức năng, giao diện và các lỗi hồi quy.
Staging: Môi trường mô phỏng gần giống Production, được sử dụng để kiểm tra trước khi phát hành chính thức.
Production: Phiên bản được cung cấp cho người dùng thật.

Mỗi môi trường thường có những thông số khác nhau. Ví dụ, Development có thể kết nối đến dev-api.example.com, trong khi Production kết nối đến api.example.com. Tài khoản, cơ sở dữ liệu, khóa dịch vụ bên thứ ba và chính sách logging cũng có thể khác nhau.

1.2. Vì sao cần nhiều môi trường?

Nếu chỉ sử dụng một môi trường duy nhất, việc phát triển trực tiếp trên hệ thống Production có thể gây ra nhiều rủi ro. Một đoạn mã chưa hoàn thiện có thể làm hỏng dữ liệu thật hoặc ảnh hưởng đến người dùng.

Ngược lại, nếu có nhiều môi trường, nhóm phát triển có thể thử nghiệm tính năng trong một phạm vi an toàn trước khi đưa vào hệ thống chính thức. Đây là nền tảng quan trọng cho quy trình CI/CD, kiểm thử tự động và phát hành ứng dụng theo từng giai đoạn.

2. Flutter Flavor là gì?

Flavor là một biến thể của ứng dụng được tạo ra từ cùng một mã nguồn nhưng có thể sở hữu cấu hình riêng. Một flavor có thể thay đổi:

– Tên hiển thị của ứng dụng.
– Application ID hoặc Bundle Identifier.
– Icon ứng dụng.
– API base URL.
– Firebase project.
– Khóa API và cấu hình dịch vụ bên thứ ba.
– Mức độ logging.
– Tính năng thử nghiệm hoặc feature flags.
– Cấu hình ký ứng dụng.

Ví dụ, từ một dự án Flutter, nhóm có thể tạo ra ba ứng dụng:
– MyApp Dev
– MyApp Staging
– MyApp

Ba ứng dụng này sử dụng cùng một codebase, nhưng mỗi ứng dụng có thể kết nối đến một backend khác nhau và cài đặt đồng thời trên cùng một thiết bị nhờ Application ID khác nhau.

3. Lợi ích của Flutter Flavors

3.1. Tách biệt cấu hình

Flavors giúp tách cấu hình theo môi trường khỏi logic nghiệp vụ. Thay vì viết nhiều điều kiện như if (isProduction), ứng dụng có thể nhận cấu hình đúng ngay từ thời điểm build hoặc khởi chạy.

3.2. Giảm rủi ro phát hành nhầm

Một trong những lỗi nguy hiểm là bản Development vô tình kết nối đến cơ sở dữ liệu Production hoặc bản Production sử dụng khóa thử nghiệm. Việc định nghĩa flavor rõ ràng giúp giảm đáng kể nguy cơ này.

3.3. Cài đặt nhiều phiên bản trên cùng thiết bị

Nếu mỗi flavor có Application ID riêng, nhà phát triển có thể cài đặt đồng thời bản Dev và bản Production. Điều này rất hữu ích khi cần so sánh hành vi giữa hai phiên bản.

3.4. Hỗ trợ tự động hóa

Flavors phù hợp với pipeline CI/CD. Hệ thống build có thể tự động tạo bản APK hoặc IPA theo từng môi trường, sau đó phân phối bản QA cho nhóm kiểm thử hoặc bản Production lên cửa hàng ứng dụng.

3.5. Dễ mở rộng

Khi dự án phát triển, nhóm có thể bổ sung thêm flavor cho khách hàng, khu vực địa lý hoặc thương hiệu khác mà không phải tạo một dự án Flutter riêng biệt.

4. Thiết kế cấu trúc môi trường

Trước khi cấu hình flavor, nhóm nên thống nhất chiến lược môi trường. Mô hình hệ thống được tổng hợp như sau:

Không phải dự án nào cũng cần đủ bốn môi trường. Một dự án nhỏ có thể chỉ cần dev, staging và prod. Điều quan trọng là quy ước phải rõ ràng, nhất quán và được ghi lại trong tài liệu của dự án.

5. Cấu hình flavor trên Android

Trên Android, flavor thường được cấu hình trong tệp android/app/build.gradle hoặc build.gradle.kts, tùy phiên bản cấu trúc dự án. Ví dụ với Gradle Groovy:

android {
    namespace "com.example.myapp"

    defaultConfig {
        applicationId "com.example.myapp"
        minSdkVersion flutter.minSdkVersion
        targetSdkVersion flutter.targetSdkVersion
        versionCode flutterVersionCode.toInteger()
        versionName flutterVersionName
    }

    flavorDimensions "environment"

    productFlavors {
        dev {
            dimension "environment"
            applicationIdSuffix ".dev"
            versionNameSuffix "-dev"
            resValue "string", "app_name", "MyApp Dev"
        }

        staging {
            dimension "environment"
            applicationIdSuffix ".staging"
            versionNameSuffix "-staging"
            resValue "string", "app_name", "MyApp Staging"
        }

        prod {
            dimension "environment"
            resValue "string", "app_name", "MyApp"
        }
    }
}

Trong ví dụ trên, applicationIdSuffix tạo ra các Application ID khác nhau:
– com.example.myapp.dev
– com.example.myapp.staging
– com.example.myapp
Nhờ đó, ba phiên bản có thể tồn tại song song trên một thiết bị Android.

Các lệnh build tương ứng có thể là:

flutter run --flavor dev -t lib/main_dev.dart
flutter run --flavor staging -t lib/main_staging.dart
flutter run --flavor prod -t lib/main_prod.dart

Để tạo bản phát hành Android:

flutter build apk --release --flavor staging -t lib/main_staging.dart
flutter build appbundle --release --flavor prod -t lib/main_prod.dart

Tên file entry point có thể thay đổi tùy cách tổ chức dự án. Điểm quan trọng là lệnh build phải chỉ rõ flavor và file khởi chạy tương ứng.

6. Cấu hình flavor trên iOS

Trên iOS, flavor thường được triển khai thông qua Xcode Schemes và Build Configurations. Đây là phần phức tạp hơn Android vì cần cấu hình nhiều thành phần liên quan đến signing, Bundle Identifier và tài nguyên ứng dụng.

Một quy trình tổng quát gồm các bước:
1. Mở thư mục ios bằng Xcode.
2. Tạo các Build Configuration như Debug-Dev, Release-Dev, Debug-Staging, Release-Staging, Debug-Prod và Release-Prod.
3. Tạo các Scheme tương ứng: dev, staging, prod.
4. Gán mỗi Scheme vào Build Configuration phù hợp.
5. Cấu hình Bundle Identifier riêng cho từng môi trường.
6. Thiết lập signing và provisioning profile phù hợp.
7. Cập nhật cấu hình trong Podfile nếu cần.

Ví dụ Bundle Identifier có thể là:
– com.example.myapp.dev
– com.example.myapp.staging
– com.example.myapp

Sau khi cấu hình, có thể chạy lệnh:

flutter run --flavor dev -t lib/main_dev.dart
flutter build ipa --release --flavor prod -t lib/main_prod.dart

Tên Scheme phải khớp với cấu hình trong Xcode. Vì cấu hình iOS dễ phát sinh lỗi signing, nhóm phát triển nên kiểm tra kỹ trên máy thật và trong hệ thống CI/CD.

7. Tổ chức các file khởi chạy trong Flutter

Một cách tổ chức phổ biến là tạo file main riêng cho từng môi trường:

lib/
├── main_dev.dart
├── main_staging.dart
├── main_prod.dart
├── app.dart
├── config/
│   ├── app_config.dart
│   ├── dev_config.dart
│   ├── staging_config.dart
│   └── prod_config.dart
└── features/

Các file khởi chạy có thể có nội dung như sau:

import 'package:flutter/material.dart';
import 'app.dart';
import 'config/app_config.dart';
 
void main() {
  const config = AppConfig(
    environment: 'dev',
    apiBaseUrl: 'https://dev-api.example.com',
    enableLogging: true,
  );
 
  runApp(MyApp(config: config));
}

File main_prod.dart có thể sử dụng cấu hình khác:

import 'package:flutter/material.dart';
import 'app.dart';
import 'config/app_config.dart';
 
void main() {
  const config = AppConfig(
    environment: 'prod',
    apiBaseUrl: 'https://api.example.com',
    enableLogging: false,
  );
 
  runApp(MyApp(config: config));
}

Lớp cấu hình có thể được định nghĩa như sau:

class AppConfig {
  final String environment;
  final String apiBaseUrl;
  final bool enableLogging;
 
  const AppConfig({
    required this.environment,
    required this.apiBaseUrl,
    required this.enableLogging,
  });
}

Cách này có ưu điểm là cấu hình được truyền tường minh vào ứng dụng. Các widget và service không cần tự suy đoán ứng dụng đang chạy ở môi trường nào.

8. Sử dụng biến môi trường và –dart-define

Ngoài flavor, Flutter còn hỗ trợ truyền biến lúc build hoặc lúc chạy thông qua –dart-define. Ví dụ:

flutter run \
  --flavor dev \
  -t lib/main.dart \
  --dart-define=APP_ENV=dev \
  --dart-define=API_BASE_URL=https://dev-api.example.com

Trong Dart, có thể đọc giá trị bằng String.fromEnvironment:

const appEnvironment = String.fromEnvironment(
  'APP_ENV',
  defaultValue: 'dev',
);
 
const apiBaseUrl = String.fromEnvironment(
  'API_BASE_URL',
  defaultValue: 'http://localhost:8080',
);

Cách này hữu ích khi muốn thay đổi một số giá trị mà không tạo quá nhiều file main. Tuy nhiên, cần hiểu rằng các giá trị được đưa vào ứng dụng có thể bị trích xuất từ binary. Vì vậy, không nên dùng –dart-define để bảo vệ secret thực sự như private key hoặc mật khẩu cơ sở dữ liệu.

Để thuận tiện, nhóm có thể lưu các lệnh trong file cấu hình hoặc script build. Ví dụ:

flutter build appbundle \
  --release \
  --flavor prod \
  -t lib/main.dart \
  --dart-define=APP_ENV=prod \
  --dart-define=API_BASE_URL=https://api.example.com

9. Quản lý Firebase theo nhiều môi trường

Firebase là một trường hợp thường cần cấu hình riêng cho từng môi trường. Ví dụ, bản Development có thể dùng Firebase project myapp-dev, còn bản Production dùng myapp-prod.

Trên Android, mỗi flavor có thể sử dụng tệp google-services.json riêng. Một cấu trúc thường gặp là:

android/app/src/
├── dev/google-services.json
├── staging/google-services.json
└── prod/google-services.json

Trên iOS, có thể đặt các tệp GoogleService-Info.plist vào các thư mục tương ứng hoặc cấu hình chúng thông qua Build Phase của Xcode.

Việc tách Firebase project giúp dữ liệu phân tích, thông báo đẩy, Crashlytics và Authentication của các môi trường không bị trộn lẫn. Đây là một thực hành rất quan trọng, đặc biệt khi ứng dụng có lượng người dùng lớn.

10. Quản lý icon, tên ứng dụng và tài nguyên riêng

Một flavor thường nên có dấu hiệu nhận biết rõ ràng để tránh nhầm lẫn. Ví dụ, bản Dev có thể sử dụng icon màu xanh hoặc tên MyApp Dev, trong khi bản Production sử dụng thương hiệu chính thức.

Các tài nguyên riêng có thể được tổ chức theo thư mục Android source set hoặc thông qua cấu hình Xcode. Ngoài icon, nhóm có thể thay đổi:
– Splash screen.
– Màu sắc nhận diện môi trường.
– Banner cảnh báo “Staging”.
– Tên hiển thị trong danh sách ứng dụng.
– Cấu hình deep link.
– Cấu hình notification channel.

Việc nhận diện trực quan đặc biệt có ích cho QA và lập trình viên, vì nó ngăn người dùng thử nghiệm thực hiện thao tác nhầm trên bản Production.

11. Flavors trong quy trình CI/CD

Flavors phát huy hiệu quả rõ nhất khi kết hợp với CI/CD. Một pipeline có thể thực hiện các bước:
1. Checkout mã nguồn.
2. Cài đặt Flutter và dependencies.
3. Chạy static analysis và unit test.
4. Build flavor tương ứng.
5. Ký ứng dụng bằng signing key của môi trường.
6. Phân phối bản build đến tester hoặc cửa hàng ứng dụng.

Ví dụ, pipeline cho Staging có thể chạy:

flutter pub get
flutter analyze
flutter test
flutter build apk \
  --release \
  --flavor staging \
  -t lib/main_staging.dart

Pipeline Production cần có quy trình kiểm soát chặt chẽ hơn, chẳng hạn như yêu cầu phê duyệt thủ công, kiểm tra phiên bản, xác minh changelog và kiểm tra signing configuration.

Một nguyên tắc quan trọng là không lưu secret trực tiếp trong repository. Các khóa ký, token và thông tin nhạy cảm nên được lưu trong secret manager của hệ thống CI/CD. File cấu hình được commit vào Git chỉ nên chứa các giá trị công khai hoặc giá trị không gây rủi ro khi bị lộ.

12. Những lỗi thường gặp

12.1. Chỉ định flavor nhưng quên entry point

Lệnh flutter run –flavor dev chưa chắc đã sử dụng đúng cấu hình Dart nếu dự án có nhiều file main. Cần chỉ rõ -t lib/main_dev.dart hoặc tổ chức logic cấu hình phù hợp.

12.2. Application ID bị trùng

Nếu các flavor dùng chung Application ID, chúng không thể cài đặt song song và có thể ghi đè lẫn nhau. Android và iOS đều cần Bundle Identifier hoặc Application ID phù hợp.

12.3. Cấu hình iOS không khớp tên Scheme

Tên flavor trong câu lệnh Flutter cần tương ứng với Scheme đã tạo trong Xcode. Chỉ cần sai khác về chữ hoa, chữ thường hoặc tên cấu hình cũng có thể làm build thất bại.

12.4. Dùng nhầm Firebase configuration

Một bản Staging dùng nhầm Firebase Production có thể gửi dữ liệu kiểm thử vào hệ thống thật. Vì vậy, cần kiểm tra cả đường dẫn file cấu hình và project ID.

12.5. Đưa secret vào mã nguồn hoặc dart-define

dart-define chỉ giúp truyền cấu hình, không phải cơ chế lưu trữ bí mật. Mọi thông tin nằm trong ứng dụng cuối cùng đều có khả năng bị phân tích.

12.6. Quá nhiều flavor không có quy ước

Nếu thêm flavor tùy tiện, dự án sẽ khó hiểu và khó bảo trì. Nhóm nên phân biệt rõ flavor phục vụ môi trường với flavor phục vụ thương hiệu, khu vực hoặc khách hàng.

13. Best practices khi sử dụng Flutter Flavors

Thứ nhất, hãy đặt tên flavor nhất quán và dễ đọc. Các tên như dev, staging và prod thường tốt hơn các tên tùy ý như alpha1, test-new hoặc release-final.
Thứ hai, nên tách cấu hình khỏi business logic. API URL, logging và feature flags nên được quản lý thông qua một lớp cấu hình hoặc dependency injection thay vì rải rác trong các widget.
Thứ ba, bản Development và Staging nên có nhận diện trực quan khác Production. Điều này làm giảm nguy cơ thao tác nhầm.
Thứ tư, cần kiểm thử pipeline cho từng flavor. Một cấu hình chạy được trên máy lập trình viên chưa chắc hoạt động trên CI/CD hoặc máy thật.
Thứ năm, hãy kiểm soát quyền truy cập theo môi trường. Developer có thể được quyền truy cập Dev và Staging, nhưng không nhất thiết được quyền phát hành Production.
Thứ sáu, tài liệu hóa cách chạy và build dự án. Một README tốt nên giải thích các lệnh như:

flutter run --flavor dev -t lib/main_dev.dart
flutter build apk --flavor staging -t lib/main_staging.dart
flutter build appbundle --flavor prod -t lib/main_prod.dart

14. Đánh giá và lựa chọn giải pháp

Flutter Flavors phù hợp khi dự án có nhiều môi trường hoặc cần tạo nhiều biến thể ứng dụng. Tuy nhiên, flavor không phải là giải pháp duy nhất cho mọi bài toán cấu hình.

Nếu dự án nhỏ, chỉ cần thay đổi API URL, –dart-define có thể là lựa chọn đơn giản hơn. Nếu dự án có nhiều khác biệt về giao diện, dịch vụ và quy trình phát hành, flavor sẽ phù hợp hơn. Trong các dự án lớn, hai phương pháp thường được dùng kết hợp: flavor quản lý biến thể cấp nền tảng, còn –dart-define truyền các giá trị linh hoạt trong pipeline.

Điều quan trọng không phải là tạo càng nhiều môi trường càng tốt, mà là thiết kế số lượng môi trường vừa đủ để hỗ trợ phát triển an toàn và hiệu quả.

Kết luận

Flutter Flavors và Multiple Environments là những thành phần quan trọng trong quy trình phát triển ứng dụng Flutter chuyên nghiệp. Flavors cho phép tạo nhiều phiên bản ứng dụng từ một codebase duy nhất, trong khi Multiple Environments giúp tách biệt quá trình phát triển, kiểm thử và phát hành.

Khi được triển khai đúng cách, giải pháp này mang lại nhiều lợi ích: giảm lỗi cấu hình, bảo vệ hệ thống Production, hỗ trợ cài đặt nhiều phiên bản song song, cải thiện quy trình CI/CD và giúp dự án dễ mở rộng. Tuy nhiên, để đạt hiệu quả, nhóm phát triển cần xây dựng quy ước rõ ràng về tên flavor, Application ID, Firebase configuration, secret management và pipeline phát hành.

Có thể xem Flutter Flavors không chỉ là công cụ build, mà còn là một phần của kiến trúc vận hành ứng dụng. Một chiến lược môi trường tốt giúp nhóm phát triển làm việc nhanh hơn, kiểm thử an toàn hơn và phát hành sản phẩm đáng tin cậy hơn.

Minh Anh

Xem tất cả bài viết của tác giả

Bài viết khác

Message Broker

1. Message Broker là gì? Message Broker là một thành phần trung gian được sử dụng để tiếp nhận, quản lý và chuyển tiếp thông điệp giữa các ứng dụng hoặc các thành phần trong một hệ thống phần mềm. Công nghệ này thường xuất hiện trong những hệ thống Backend, kiến trúc Microservices và […]

Đọc thêm

Background Jobs and Queues

1. Background Jobs and Queues là gì? Background Jobs & Queues là hai khái niệm thường gặp trong quá trình phát triển phần mềm, đặc biệt là khi xây dựng các ứng dụng web, ứng dụng di động hoặc những hệ thống cần xử lý nhiều yêu cầu cùng lúc. Hai khái niệm này liên […]

Đọc thêm

Redis and Caching

1. Caching là gì? Caching là kỹ thuật lưu trữ tạm thời những dữ liệu thường xuyên được sử dụng để có thể truy xuất lại nhanh chóng khi cần thiết. Thay vì mỗi lần người dùng thực hiện một thao tác, hệ thống đều phải truy vấn cơ sở dữ liệu hoặc xử lý […]

Đọc thêm

Database Migration

1. Database Migration là gì? Database Migration là quá trình quản lý và cập nhật cấu trúc cơ sở dữ liệu theo từng phiên bản trong quá trình phát triển phần mềm. Khi xây dựng một ứng dụng, cơ sở dữ liệu thường xuyên thay đổi để đáp ứng các yêu cầu mới. Ví dụ, […]

Đọc thêm

Bun ORM

1. Bun ORM là gì? Bun ORM là một thư viện ORM dành cho ngôn ngữ lập trình Go (Golang), được sử dụng để làm việc với cơ sở dữ liệu quan hệ. Bun giúp lập trình viên xây dựng và thực hiện các truy vấn database thông qua những cấu trúc dữ liệu và […]

Đọc thêm

Date / Number / Currency Formatting

       Trong quá trình phát triển phần mềm, đặc biệt là các ứng dụng web và di động phục vụ người dùng ở nhiều quốc gia, việc hiển thị dữ liệu theo đúng định dạng ngày tháng, số và tiền tệ đóng vai trò vô cùng quan trọng. Người dùng không chỉ quan […]

Đọc thêm