ios-diia开发规范手册：从编码风格到架构原则

ios-diia开发规范手册：从编码风格到架构原则

【免费下载链接】ios-diia 项目地址: https://gitcode.com/GitHub_Trending/io/ios-diia

1. 项目概述与环境配置

ios-diia是某数字转型部开发的旗舰产品Diia的开源实现，提供公民数字文档和政府服务访问功能。本手册将详细介绍项目的开发规范，包括编码风格、架构原则、模块划分等关键内容，帮助开发人员快速融入项目并保持代码质量的一致性。

1.1 环境配置

项目使用.xcconfig文件进行环境配置，分别为开发环境和生产环境提供不同的配置参数。开发环境配置文件DiiaDev.xcconfig包含以下关键配置：

// API
API_BASE_URL = api2oss.diia.gov.ua

// APP SETTINGS
APP_NAME = DiiaOS
APP_BUNDLE_ID = ua.gov.diia.opensource.app
SCHEME = DiiaDev

这些配置定义了API基础URL、应用名称、Bundle ID和运行方案，开发人员应根据实际需求进行调整。

2. 编码风格规范

2.1 Swift编码规范

项目遵循Swift语言的通用编码规范，同时有一些特定的约定需要遵守：

2.1.1 命名规范

• 类型命名：使用UpperCamelCase，如DocumentsReorderingViewController
• 方法和变量命名：使用lowerCamelCase，如onBackTapped()、isBiometryEnabled
• 常量命名：使用UPPER_SNAKE_CASE，如API_BASE_URL

2.1.2 代码格式

• 使用4个空格缩进，不使用Tab
• 每行代码长度控制在120个字符以内
• 函数之间保留一个空行，逻辑块之间保留一个空行

2.1.3 扩展使用

项目广泛使用Swift的扩展(Extension)功能来组织代码，将相关功能放在同一个扩展中。例如，String+Ext.swift中定义了字符串的解码扩展：

extension String {
    func parseDecodable<T>(decoder: JSONDecoder = JSONDecoderConfig().jsonDecoder()) -> T? where T: Decodable {
        let data = Data(self.utf8)
        return try? decoder.decode(T.self, from: data)
    }
}

2.2 特定模块编码规范

2.2.1 视图控制器(ViewController)

所有视图控制器都应继承自UIViewController，并遵循单一职责原则。例如，DocumentsReorderingViewController只负责文档重排序相关的视图逻辑。

2.2.2 数据模型

数据模型应使用struct而非class，并遵循Decodable协议以便于JSON解析。项目中提供了JSONDecoderConfig.swift来统一配置JSON解码器：

struct JSONDecoderConfig: JSONDecoderConfigProtocol {
    let dateDecodingStrategy: JSONDecoder.DateDecodingStrategy = .customISO8601
    let dataDecodingStrategy: JSONDecoder.DataDecodingStrategy = .deferredToData
    let nonConformingFloatDecodingStrategy: JSONDecoder.NonConformingFloatDecodingStrategy = .throw
    let keyDecodingStrategy: JSONDecoder.KeyDecodingStrategy = .useDefaultKeys
    
    func jsonDecoder() -> JSONDecoder {
        let decoder = JSONDecoder()
        decoder.dataDecodingStrategy = dataDecodingStrategy
        decoder.dateDecodingStrategy = dateDecodingStrategy
        decoder.nonConformingFloatDecodingStrategy = nonConformingFloatDecodingStrategy
        decoder.keyDecodingStrategy = keyDecodingStrategy
        
        return decoder
    }
}

3. 架构设计原则

3.1 MVP架构模式

项目采用MVP(Model-View-Presenter)架构模式，将业务逻辑与视图逻辑分离。

3.1.1 模块组成

每个功能模块通常包含以下组件：

• Model：数据模型和业务逻辑
• View：视图控制器(ViewController)和视图组件
• Presenter：协调Model和View，处理用户交互

例如，文档重排序模块包含：

• DocumentsReorderingViewController (View)
• DocumentsReorderingPresenter (Presenter)

3.1.2 Presenter协议

每个Presenter都应遵循一个对应的协议，定义对外暴露的方法。例如：

protocol DocumentsReorderingAction: BasePresenter {
    func onBackTapped()
    func numberOfItems() -> Int
    func item(at index: Int) -> DocReorderingCellViewModel
    func moveItem(from index: Int, toIndex: Int)
}

这样的设计使得View和Presenter之间的依赖更加清晰，也便于单元测试。

3.2 模块化设计

项目采用模块化设计，将功能划分为多个独立的模块，如授权模块、文档模块、公共服务模块等。每个模块内部遵循高内聚低耦合的原则，模块之间通过明确定义的接口进行通信。

4. 关键功能实现规范

4.1 网络请求

项目的网络请求功能由NetworkConfigurator.swift统一配置，包括SSL证书固定、请求拦截器等。以下是证书固定的实现代码：

func activeServerTrustPolicies() -> [String: ServerTrustEvaluating] {
    let activeScheme = SchemeType(rawValue: EnvironmentVars.scheme)
    var currentCertTrustEvaluator: ServerTrustEvaluating
    
    switch activeScheme {
    case .dev:
        currentCertTrustEvaluator = DisabledTrustEvaluator()
    case .prod:
        currentCertTrustEvaluator = prodPinnedCertificatesTrustEvaluator()
    default:
        currentCertTrustEvaluator = DisabledTrustEvaluator()
    }
    let serverTrustPolicies: [String: ServerTrustEvaluating] = [
        EnvironmentVars.baseApiHost: currentCertTrustEvaluator
    ]
    return serverTrustPolicies
}

在开发环境中禁用证书验证，便于调试；在生产环境中启用证书固定，提高安全性。

4.2 本地存储

项目使用StoreHelper进行本地数据存储，封装了UserDefaults的操作。例如，PinCodeStorage.swift中使用StoreHelper存储生物识别启用状态：

func getIsBiometryEnabled() -> Bool? {
    return storage.getValue(forKey: .isBiometryEnabled)
}

4.3 UI组件

项目定义了一套统一的UI组件规范，所有自定义视图都应遵循这些规范。例如，UIView+CustomCorners.swift提供了设置圆角的扩展方法：

extension UIView {
    func cornerRadius(_ radius: CGFloat, for corners: UIRectCorner) {
        let maskPath = UIBezierPath(roundedRect: self.bounds,
                                    byRoundingCorners: corners,
                                    cornerRadii: CGSize(width: radius, height: radius))
        
        let maskLayer = CAShapeLayer()
        maskLayer.path = maskPath.cgPath
        self.layer.mask = maskLayer
    }
}

5. 资源管理

5.1 图片资源

项目的图片资源集中放在Assets.xcassets目录下，按功能进行分组。例如，light_background.imageset包含应用的浅色背景图片：

开发人员应使用Asset Catalog管理图片资源，避免直接将图片文件放在项目目录中。

5.2 字符串资源

所有字符串资源应放在Localizable.strings文件中，支持多语言本地化。使用时通过NSLocalizedString函数获取：

let title = NSLocalizedString("documents.reorder.title", comment: "Documents reorder title")

6. 测试与调试

6.1 单元测试

项目的单元测试应遵循以下规范：

• 测试类命名格式：[类名]Tests，如PinCodeStorageTests
• 测试方法命名格式：test[方法名]_[条件]_[预期结果]，如testMoveItem_fromIndex0_toIndex1_updatesOrder
• 每个测试方法应只测试一个功能点

6.2 调试技巧

• 使用print或debugPrint输出调试信息，避免使用NSLog
• 关键逻辑处添加断言(Assertion)，如assert(index >= 0, "Index should be non-negative")
• 使用Xcode的断点调试功能，结合条件断点提高调试效率

7. 项目目录结构

项目采用以下目录结构组织代码：

DiiaOpenSource/
├── AppDelegate.swift           # 应用入口
├── Common/                     # 通用组件和工具类
│   ├── Extensions/             # Swift扩展
│   ├── Networking/             # 网络相关
│   └── Services/               # 服务类
├── Modules/                    # 功能模块
│   ├── Authorization/          # 授权模块
│   ├── Documents/              # 文档模块
│   └── PublicServices/         # 公共服务模块
├── Resources/                  # 资源文件
│   ├── Assets.xcassets/        # 图片资源
│   └── Strings/                # 字符串资源
└── SupportingFiles/            # 配置文件
    └── Configurations/         # 环境配置

开发人员应将新功能按照此结构放置在相应的目录中，保持项目结构清晰。

8. 总结

本手册详细介绍了ios-diia项目的开发规范，包括环境配置、编码风格、架构设计、关键功能实现等方面。遵循这些规范有助于提高代码质量、降低维护成本、促进团队协作。开发人员在实际工作中应灵活运用这些规范，并根据项目发展不断优化和完善。

更多项目详情，请参考README.md和CONTRIBUTING.md。

【免费下载链接】ios-diia 项目地址: https://gitcode.com/GitHub_Trending/io/ios-diia