Swift CLI工具开发入门

一、Swift 与 CLI 工具简介

1.1 Swift 语言特性

Swift 是一种由苹果公司开发的编程语言，具有现代、安全、高效等特点。它融合了 C 和 Objective - C 的优点，同时引入了许多新的语言特性。例如，Swift 有强大的类型推断系统，使得开发者在编写代码时无需频繁显式声明变量类型，编译器可以根据上下文自动推断。

let number = 42 // 编译器推断 number 为 Int 类型

Swift 还支持面向对象编程、函数式编程和协议导向编程范式。面向对象编程方面，它有类、继承、属性和方法等概念；函数式编程特性包括闭包、高阶函数等；协议导向编程则允许开发者通过协议来定义行为，类型遵循协议来提供具体实现。

1.2 CLI 工具概述

CLI（Command - Line Interface，命令行界面）工具是通过命令行与用户交互的程序。它们在系统管理、自动化脚本、软件开发流程等方面有着广泛应用。例如，Git 就是一个非常流行的 CLI 工具，用于版本控制。CLI 工具通常具有简洁高效的特点，通过命令和参数的组合来执行特定任务。与图形界面应用相比，CLI 工具在处理批量任务、远程操作等场景下优势明显。

二、开发环境搭建

2.1 安装 Swift

要开发 Swift CLI 工具，首先需要安装 Swift 环境。对于 macOS 用户，Swift 通常随 Xcode 一起安装。如果未安装 Xcode，可以通过 Homebrew 安装 Swift：

brew install swift

对于 Linux 用户，可以从 Swift 官方网站下载适合自己系统版本的 Swift 安装包，并按照官方文档的指引进行安装。

2.2 选择开发工具

虽然可以使用任何文本编辑器来编写 Swift 代码，但为了提高开发效率，推荐使用 Xcode（在 macOS 上）或 Visual Studio Code 并安装 Swift 扩展。Xcode 提供了强大的代码自动完成、语法检查和调试功能，非常适合 Swift 开发。Visual Studio Code 则以其轻量级、可扩展性强而受到欢迎，配合 Swift 扩展可以实现高效的代码编辑和调试。

三、创建第一个 Swift CLI 工具项目

3.1 使用 Swift Package Manager 创建项目

Swift Package Manager（SPM）是 Swift 官方的包管理工具，用于创建、构建和管理 Swift 项目。要创建一个新的 CLI 工具项目，打开终端并执行以下命令：

mkdir myCLItool
cd myCLItool
swift package init --type executable

上述命令首先创建一个名为 myCLItool 的目录，然后进入该目录，并使用 SPM 创建一个可执行类型的项目。项目创建完成后，目录结构如下：

myCLItool/
├── Package.swift
└── Sources
    └── myCLItool
        └── main.swift

Package.swift 文件定义了项目的元数据，如名称、依赖等。Sources/myCLItool/main.swift 是项目的入口文件，所有的代码逻辑将从这里开始执行。

3.2 简单的 Hello World 示例

打开 main.swift 文件，编写以下代码：

import Foundation

print("Hello, World!")

在终端中，进入项目目录并执行以下命令来构建和运行项目：

swift build
.build/debug/myCLItool

执行 swift build 命令会编译项目并生成可执行文件，位于 .build/debug 目录下。运行生成的可执行文件，将会在终端输出 Hello, World!。

四、解析命令行参数

4.1 使用 CommandLine 类

Swift 标准库中的 CommandLine 类提供了访问命令行参数的功能。CommandLine.arguments 是一个包含所有命令行参数的数组，其中 CommandLine.arguments[0] 是可执行文件的路径，从 CommandLine.arguments[1] 开始是用户输入的实际参数。

以下是一个简单示例，该示例接收两个数字作为参数，并计算它们的和：

import Foundation

guard CommandLine.arguments.count == 3 else {
    print("Usage: myCLItool <number1> <number2>")
    exit(1)
}

let number1 = Double(CommandLine.arguments[1])
let number2 = Double(CommandLine.arguments[2])

guard let num1 = number1, let num2 = number2 else {
    print("Invalid input. Please provide valid numbers.")
    exit(1)
}

let sum = num1 + num2
print("The sum of \(num1) and \(num2) is \(sum)")

在上述代码中，首先检查参数个数是否为 3（包括可执行文件路径和两个数字参数）。如果参数个数不正确，输出使用说明并退出程序。然后尝试将参数转换为 Double 类型，如果转换失败，同样输出错误信息并退出。最后计算并输出两个数字的和。

4.2 使用第三方库解析参数

虽然 CommandLine 类可以满足基本的参数解析需求，但对于复杂的参数解析场景，使用第三方库会更加方便。例如，ArgumentParser 库是一个功能强大的命令行参数解析库，可用于创建功能丰富、用户友好的 CLI 工具。

首先，在 Package.swift 文件中添加依赖：

// swift-tools-version:5.5
import PackageDescription

let package = Package(
    name: "myCLItool",
    dependencies: [
       .package(url: "https://github.com/apple/swift-argument-parser", from: "1.0.0")
    ],
    targets: [
       .target(
            name: "myCLItool",
            dependencies: ["ArgumentParser"]),
       .testTarget(
            name: "myCLItoolTests",
            dependencies: ["myCLItool"]),
    ]
)

然后在 main.swift 文件中使用 ArgumentParser 库：

import ArgumentParser

struct MyCLI: ParsableCommand {
    @Argument(help: "The first number")
    var number1: Double
    
    @Argument(help: "The second number")
    var number2: Double
    
    func run() {
        let sum = number1 + number2
        print("The sum of \(number1) and \(number2) is \(sum)")
    }
}

MyCLI.main()

在上述代码中，定义了一个 MyCLI 结构体，它遵循 ParsableCommand 协议。@Argument 属性用于定义命令行参数，run 方法包含了实际的业务逻辑。最后通过调用 MyCLI.main() 来启动命令行工具。

五、实现 CLI 工具的功能逻辑

5.1 文件操作

许多 CLI 工具需要进行文件操作，比如读取文件内容、写入文件等。Swift 提供了方便的 FileManager 和 Data 类来处理文件相关操作。

以下是一个简单示例，读取指定文件的内容并输出到终端：

import Foundation

guard CommandLine.arguments.count == 2 else {
    print("Usage: myCLItool <filePath>")
    exit(1)
}

let filePath = CommandLine.arguments[1]
let fileManager = FileManager.default

if!fileManager.fileExists(atPath: filePath) {
    print("File does not exist: \(filePath)")
    exit(1)
}

do {
    let data = try Data(contentsOf: URL(fileURLWithPath: filePath))
    if let content = String(data: data, encoding:.utf8) {
        print(content)
    } else {
        print("Could not decode file content as UTF - 8")
    }
} catch {
    print("Error reading file: \(error)")
}

上述代码首先检查是否提供了文件路径作为参数，然后检查文件是否存在。如果文件存在，尝试读取文件内容并将其转换为字符串输出。如果读取或转换过程中出现错误，输出相应的错误信息。

5.2 网络请求

在一些场景下，CLI 工具可能需要进行网络请求，例如获取远程数据。Swift 中可以使用 URLSession 来实现网络请求功能。

以下是一个简单示例，发送一个 GET 请求到指定 URL 并输出响应内容：

import Foundation

guard CommandLine.arguments.count == 2 else {
    print("Usage: myCLItool <url>")
    exit(1)
}

let urlString = CommandLine.arguments[1]
guard let url = URL(string: urlString) else {
    print("Invalid URL: \(urlString)")
    exit(1)
}

let task = URLSession.shared.dataTask(with: url) { data, response, error in
    guard let data = data, error == nil else {
        print(error?.localizedDescription?? "No data")
        return
    }
    if let httpResponse = response as? HTTPURLResponse {
        print("Status code: \(httpResponse.statusCode)")
    }
    if let content = String(data: data, encoding:.utf8) {
        print(content)
    }
}
task.resume()

上述代码首先检查是否提供了 URL 作为参数，然后将字符串转换为 URL。接着使用 URLSession.shared.dataTask 创建一个数据任务，发送网络请求。在响应处理中，输出状态码和响应内容。

六、错误处理与日志记录

6.1 错误处理

在 CLI 工具开发中，错误处理至关重要。Swift 提供了多种错误处理机制，如 do - catch 块、try? 和 try!。

对于前面读取文件的示例，可以将错误处理优化为：

import Foundation

guard CommandLine.arguments.count == 2 else {
    print("Usage: myCLItool <filePath>")
    exit(1)
}

let filePath = CommandLine.arguments[1]
let fileManager = FileManager.default

if!fileManager.fileExists(atPath: filePath) {
    print("File does not exist: \(filePath)")
    exit(1)
}

if let content = try? String(contentsOf: URL(fileURLWithPath: filePath), encoding:.utf8) {
    print(content)
} else {
    print("Error reading file or decoding content")
}

在上述代码中，使用 try? 来尝试读取文件内容并转换为字符串。如果操作成功，try? 返回一个可选值，否则返回 nil。这样可以简化错误处理代码，适用于错误情况不会导致程序严重崩溃的场景。

6.2 日志记录

日志记录对于调试和排查问题非常有帮助。虽然 Swift 标准库没有内置专门的日志记录模块，但可以通过扩展 print 函数来实现简单的日志记录功能。

func log(_ message: String, level: String = "INFO") {
    let dateFormatter = DateFormatter()
    dateFormatter.dateFormat = "yyyy - MM - dd HH:mm:ss"
    let timestamp = dateFormatter.string(from: Date())
    print("\(timestamp) [\(level)] \(message)")
}

在上述代码中，定义了一个 log 函数，它接收一个消息字符串和一个日志级别（默认为 INFO）。函数会在消息前添加时间戳和日志级别并输出。在实际使用中，可以在关键代码位置调用 log 函数记录日志。

log("Starting file read operation", level: "DEBUG")
if let content = try? String(contentsOf: URL(fileURLWithPath: filePath), encoding:.utf8) {
    log("File read successfully", level: "DEBUG")
    print(content)
} else {
    log("Error reading file or decoding content", level: "ERROR")
}

通过这种方式，可以方便地记录程序运行过程中的关键信息，便于调试和问题定位。

七、测试 CLI 工具

7.1 单元测试基础

单元测试是保证代码质量的重要手段。在 Swift 项目中，可以使用 XCTest 框架进行单元测试。对于使用 SPM 创建的项目，测试文件位于 Tests 目录下。

例如，对于前面计算两个数字和的 CLI 工具，假设将计算逻辑封装到一个函数中：

func addNumbers(_ num1: Double, _ num2: Double) -> Double {
    return num1 + num2
}

在测试文件 myCLItoolTests.swift 中编写测试代码：

import XCTest
@testable import myCLItool

class myCLItoolTests: XCTestCase {
    func testAddNumbers() {
        let result = addNumbers(2.0, 3.0)
        XCTAssertEqual(result, 5.0)
    }
}

在上述代码中，首先导入 XCTest 框架和要测试的模块 myCLItool。然后定义一个测试类 myCLItoolTests，它继承自 XCTestCase。在测试类中定义了一个测试方法 testAddNumbers，用于测试 addNumbers 函数的正确性。XCTAssertEqual 用于断言实际结果与预期结果是否相等。

7.2 测试命令行参数解析

对于命令行参数解析部分的代码，也可以进行单元测试。例如，对于使用 ArgumentParser 库的代码，可以测试参数解析的正确性。

假设定义了一个新的 ParsableCommand 结构体：

struct MyNewCLI: ParsableCommand {
    @Argument(help: "The first value")
    var value1: Int
    
    @Argument(help: "The second value")
    var value2: Int
    
    func run() {
        let sum = value1 + value2
        print("Sum: \(sum)")
    }
}

在测试文件中编写测试代码：

import XCTest
import ArgumentParser
@testable import myCLItool

class MyNewCLITests: XCTestCase {
    func testArgumentParsing() throws {
        let input = ["myCLItool", "2", "3"]
        let cli = try MyNewCLI.parse(as: input)
        XCTAssertEqual(cli.value1, 2)
        XCTAssertEqual(cli.value2, 3)
    }
}

在上述代码中，使用 try MyNewCLI.parse(as: input) 来模拟解析命令行参数，然后断言解析得到的参数值是否正确。

八、发布与分发 CLI 工具

8.1 构建可执行文件

在开发完成并通过测试后，需要构建可执行文件以便发布。对于使用 SPM 创建的项目，可以执行以下命令构建发布版本：

swift build -c release

上述命令会在 .build/release 目录下生成优化后的可执行文件。可以将该可执行文件复制到其他系统上运行，前提是目标系统安装了兼容的 Swift 运行时环境。

8.2 分发方式

1. 二进制分发：可以将构建好的可执行文件直接提供给用户下载。这种方式简单直接，但需要考虑不同操作系统和架构的兼容性。例如，对于 macOS，需要提供不同版本的可执行文件以支持 Intel 和 Apple Silicon 架构。
2. 包管理器分发：对于 macOS 用户，可以通过 Homebrew 等包管理器分发 CLI 工具。首先需要将项目发布到 Homebrew 的仓库中，用户可以通过 brew install 命令安装工具。对于 Linux 用户，可以考虑将项目发布到相应的 Linux 包管理器仓库中，如 apt 或 yum 仓库。
3. 源代码分发：提供项目的源代码，让用户自行编译安装。这种方式适用于技术水平较高的用户，并且可以根据用户的特定需求进行定制编译。但需要用户具备一定的开发环境和编译能力。

通过以上步骤，开发者可以逐步掌握 Swift CLI 工具的开发，从创建项目、解析参数、实现功能逻辑，到错误处理、测试以及最终的发布与分发，构建出功能强大、稳定可靠的 CLI 工具。