Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

x-i18n: generated_at: “2026-03-01T13:36:13Z” model: gemini-3-flash-preview provider: google-gemini-cli source_hash: e7e7b8a143345a7deaf64163ea8a728526fe6d6af6e42f3a5191cd682ae0f268 source_path: ch03-03-how-functions-work.md workflow: 16

函数 (Functions)

Functions

函数在 Rust 代码中无处不在。你已经见过该语言中最重要的函数之一：main 函数，它是许多程序的入口点。你还见过 fn 关键字，它允许你声明新函数。

Functions are prevalent in Rust code. You’ve already seen one of the most important functions in the language: the main function, which is the entry point of many programs. You’ve also seen the fn keyword, which allows you to declare new functions.

Rust 代码使用“蛇形命名法 (snake case)”作为函数和变量名的常规风格，其中所有字母均为小写，并用下划线分隔单词。下面是一个包含示例函数定义的程序：

Rust code uses snake case as the conventional style for function and variable names, in which all letters are lowercase and underscores separate words. Here’s a program that contains an example function definition:

文件名: src/main.rs

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch03-common-programming-concepts/no-listing-16-functions/src/main.rs}}
}

我们在 Rust 中通过输入 fn 后跟函数名和一对圆括号来定义函数。花括号告诉编译器函数体的开始和结束位置。

We define a function in Rust by entering fn followed by a function name and a set of parentheses. The curly brackets tell the compiler where the function body begins and ends.

我们可以通过输入函数名后跟一对圆括号来调用定义的任何函数。因为 another_function 是在程序中定义的，所以可以在 main 函数内部调用它。注意，我们在源代码中的 main 函数“之后”定义了 another_function；我们也可以在它之前定义。Rust 不在乎你在哪里定义函数，只要它们被定义在调用者可见的某个作用域内即可。

We can call any function we’ve defined by entering its name followed by a set of parentheses. Because another_function is defined in the program, it can be called from inside the main function. Note that we defined another_function after the main function in the source code; we could have defined it before as well. Rust doesn’t care where you define your functions, only that they’re defined somewhere in a scope that can be seen by the caller.

让我们开始一个名为 functions 的新二进制项目，以进一步探索函数。将 another_function 示例放入 src/main.rs 中并运行它。你应该会看到以下输出：

Let’s start a new binary project named functions to explore functions further. Place the another_function example in src/main.rs and run it. You should see the following output:

{{#include ../listings/ch03-common-programming-concepts/no-listing-16-functions/output.txt}}

各行按其在 main 函数中出现的顺序执行。首先打印 “Hello, world!” 消息，然后调用 another_function 并打印其消息。

The lines execute in the order in which they appear in the main function. First the “Hello, world!” message prints, and then another_function is called and its message is printed.

参数 (Parameters)

Parameters

我们在定义函数时可以设置“参数 (parameters)”，它们是函数签名的一部分。当函数有参数时，你可以为这些参数提供具体的值。从技术上讲，这些具体的值被称为“实参 (arguments)”，但在日常谈话中，人们往往倾向于将“形参 (parameter)”和“实参 (argument)”这两个词混用，既指函数定义中的变量，也指调用函数时传入的具体值。

We can define functions to have parameters, which are special variables that are part of a function’s signature. When a function has parameters, you can provide it with concrete values for those parameters. Technically, the concrete values are called arguments, but in casual conversation, people tend to use the words parameter and argument interchangeably for either the variables in a function’s definition or the concrete values passed in when you call a function.

在这个版本的 another_function 中，我们添加了一个参数：

In this version of another_function we add a parameter:

文件名: src/main.rs

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch03-common-programming-concepts/no-listing-17-functions-with-parameters/src/main.rs}}
}

尝试运行此程序；你应该会得到以下输出：

Try running this program; you should get the following output:

{{#include ../listings/ch03-common-programming-concepts/no-listing-17-functions-with-parameters/output.txt}}

another_function 的声明有一个名为 x 的参数。x 的类型被指定为 i32。当我们向 another_function 传入 5 时，println! 宏会将格式字符串中包含 x 的那对花括号替换为 5。

The declaration of another_function has one parameter named x. The type of x is specified as i32. When we pass 5 in to another_function, the println! macro puts 5 where the pair of curly brackets containing x was in the format string.

在函数签名中，你“必须”声明每个参数的类型。这是 Rust 设计中的一个深思熟虑的决定：要求在函数定义中进行类型注解，意味着编译器几乎永远不需要你在代码的其他地方使用它们来弄清楚你的意图。如果编译器知道函数期望的类型，它也能提供更有帮助的错误消息。

In function signatures, you must declare the type of each parameter. This is a deliberate decision in Rust’s design: Requiring type annotations in function definitions means the compiler almost never needs you to use them elsewhere in the code to figure out what type you mean. The compiler is also able to give more-helpful error messages if it knows what types the function expects.

定义多个参数时，请用逗号分隔参数声明，如下所示：

When defining multiple parameters, separate the parameter declarations with commas, like this:

文件名: src/main.rs

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch03-common-programming-concepts/no-listing-18-functions-with-multiple-parameters/src/main.rs}}
}

这个例子创建了一个名为 print_labeled_measurement 的函数，它有两个参数。第一个参数名为 value，类型是 i32。第二个参数名为 unit_label，类型是 char。该函数随后打印包含 value 和 unit_label 的文本。

This example creates a function named print_labeled_measurement with two parameters. The first parameter is named value and is an i32. The second is named unit_label and is type char. The function then prints text containing both the value and the unit_label.

让我们尝试运行这段代码。将当前 functions 项目中 src/main.rs 文件的内容替换为前面的示例，并使用 cargo run 运行它：

Let’s try running this code. Replace the program currently in your functions project’s src/main.rs file with the preceding example and run it using cargo run:

{{#include ../listings/ch03-common-programming-concepts/no-listing-18-functions-with-multiple-parameters/output.txt}}

因为我们调用该函数时，value 的值为 5，unit_label 的值为 'h'，所以程序输出中包含了这些值。

Because we called the function with 5 as the value for value and 'h' as the value for unit_label, the program output contains those values.

语句与表达式 (Statements and Expressions)

Statements and Expressions

函数体由一系列语句组成，可选地以一个表达式结尾。到目前为止，我们介绍的函数还不包含结尾表达式，但你已经见过表达式作为语句的一部分。因为 Rust 是一门基于表达式的语言，所以这是一个需要理解的重要区别。其他语言没有这种区别，所以让我们来看看什么是语句和表达式，以及它们的区别如何影响函数体。

Function bodies are made up of a series of statements optionally ending in an expression. So far, the functions we’ve covered haven’t included an ending expression, but you have seen an expression as part of a statement. Because Rust is an expression-based language, this is an important distinction to understand. Other languages don’t have the same distinctions, so let’s look at what statements and expressions are and how their differences affect the bodies of functions.

  • “语句 (Statements)”是执行某些操作且不返回值的指令。

  • “表达式 (Expressions)”求值得出一个结果值。

  • Statements are instructions that perform some action and do not return a value.

  • Expressions evaluate to a resultant value.

让我们看一些例子。

Let’s look at some examples.

实际上我们已经使用过语句和表达式了。使用 let 关键字创建变量并为其赋值就是一条语句。在示例 3-1 中，let y = 6; 是一条语句。

We’ve actually already used statements and expressions. Creating a variable and assigning a value to it with the let keyword is a statement. In Listing 3-1, let y = 6; is a statement.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch03-common-programming-concepts/listing-03-01/src/main.rs}}
}

函数定义也是语句；前面的整个示例本身就是一条语句。（不过，正如我们稍后将看到的，调用函数并不是一条语句。）

Function definitions are also statements; the entire preceding example is a statement in itself. (As we’ll see shortly, calling a function is not a statement, though.)

语句不返回值。因此，你不能像下面的代码尝试做的那样，将 let 语句赋值给另一个变量；你会得到一个错误：

Statements do not return values. Therefore, you can’t assign a let statement to another variable, as the following code tries to do; you’ll get an error:

文件名: src/main.rs

{{#rustdoc_include ../listings/ch03-common-programming-concepts/no-listing-19-statements-vs-expressions/src/main.rs}}

当你运行此程序时，你得到的错误看起来像这样：

When you run this program, the error you’ll get looks like this:

{{#include ../listings/ch03-common-programming-concepts/no-listing-19-statements-vs-expressions/output.txt}}

let y = 6 语句不返回值，所以 x 没有可以绑定的内容。这与其他语言（如 C 和 Ruby）中发生的情况不同，在这些语言中，赋值操作会返回所赋的值。在这些语言中，你可以编写 x = y = 6，并让 x 和 y 的值都为 6；而在 Rust 中并非如此。

The let y = 6 statement does not return a value, so there isn’t anything for x to bind to. This is different from what happens in other languages, such as C and Ruby, where the assignment returns the value of the assignment. In those languages, you can write x = y = 6 and have both x and y have the value 6; that is not the case in Rust.

表达式求得一个值，构成了你在 Rust 中编写的大部分代码。考虑一个数学运算，例如 5 + 6，这是一个求得值 11 的表达式。表达式可以是语句的一部分：在示例 3-1 中，语句 let y = 6; 中的 6 是一个求得值 6 的表达式。调用函数是一个表达式。调用宏是一个表达式。用花括号创建的新作用域块也是一个表达式，例如：

Expressions evaluate to a value and make up most of the rest of the code that you’ll write in Rust. Consider a math operation, such as 5 + 6, which is an expression that evaluates to the value 11. Expressions can be part of statements: In Listing 3-1, the 6 in the statement let y = 6; is an expression that evaluates to the value 6. Calling a function is an expression. Calling a macro is an expression. A new scope block created with curly brackets is an expression, for example:

文件名: src/main.rs

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch03-common-programming-concepts/no-listing-20-blocks-are-expressions/src/main.rs}}
}

这个表达式：

This expression:

{
    let x = 3;
    x + 1
}

是一个在该例中求值为 4 的代码块。作为 let 语句的一部分，该值被绑定到 y。注意 x + 1 这一行最后没有分号，这与你目前见过的大多数行不同。表达式不包含结尾分号。如果你在表达式的结尾添加分号，你就把它变成了语句，它就不会返回值。在接下来探索函数返回值和表达式时，请记住这一点。

is a block that, in this case, evaluates to 4. That value gets bound to y as part of the let statement. Note the x + 1 line without a semicolon at the end, which is unlike most of the lines you’ve seen so far. Expressions do not include ending semicolons. If you add a semicolon to the end of an expression, you turn it into a statement, and it will then not return a value. Keep this in mind as you explore function return values and expressions next.

具有返回值的函数 (Functions with Return Values)

Functions with Return Values

函数可以向调用它们的代码返回值。我们不命名返回值，但必须在箭头 (->) 后声明它们的类型。在 Rust 中，函数的返回值与函数体代码块中最后一个表达式的值同义。你可以通过使用 return 关键字并指定一个值从函数中提前返回，但大多数函数会隐式地返回最后一个表达式。下面是一个返回值的函数示例：

Functions can return values to the code that calls them. We don’t name return values, but we must declare their type after an arrow (->). In Rust, the return value of the function is synonymous with the value of the final expression in the block of the body of a function. You can return early from a function by using the return keyword and specifying a value, but most functions return the last expression implicitly. Here’s an example of a function that returns a value:

文件名: src/main.rs

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch03-common-programming-concepts/no-listing-21-function-return-values/src/main.rs}}
}

在 five 函数中没有函数调用、宏，甚至没有 let 语句——只有数字 5 本身。这在 Rust 中是一个完全有效的函数。注意，该函数的返回类型也被指定了，为 -> i32。尝试运行这段代码；输出应该如下所示：

There are no function calls, macros, or even let statements in the five function—just the number 5 by itself. That’s a perfectly valid function in Rust. Note that the function’s return type is specified too, as -> i32. Try running this code; the output should look like this:

{{#include ../listings/ch03-common-programming-concepts/no-listing-21-function-return-values/output.txt}}

five 中的 5 是函数的返回值，这就是为什么返回类型是 i32。让我们更详细地检查一下。有两个重要的部分：首先，let x = five(); 这一行显示我们正在使用函数的返回值来初始化一个变量。因为函数 five 返回 5，所以该行与以下代码等同：

The 5 in five is the function’s return value, which is why the return type is i32. Let’s examine this in more detail. There are two important bits: First, the line let x = five(); shows that we’re using the return value of a function to initialize a variable. Because the function five returns a 5, that line is the same as the following:

#![allow(unused)]
fn main() {
let x = 5;
}

其次，five 函数没有参数并定义了返回值的类型，但函数体是一个孤零零的 5，没有分号，因为它是我们想要返回其值的表达式。

Second, the five function has no parameters and defines the type of the return value, but the body of the function is a lonely 5 with no semicolon because it’s an expression whose value we want to return.

让我们看另一个例子：

Let’s look at another example:

文件名: src/main.rs

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch03-common-programming-concepts/no-listing-22-function-parameter-and-return/src/main.rs}}
}

运行这段代码将打印 The value of x is: 6。但如果我们在包含 x + 1 的行末尾加上分号，将其从表达式改为语句，会发生什么呢？

Running this code will print The value of x is: 6. But what happens if we place a semicolon at the end of the line containing x + 1, changing it from an expression to a statement?

文件名: src/main.rs

{{#rustdoc_include ../listings/ch03-common-programming-concepts/no-listing-23-statements-dont-return-values/src/main.rs}}

编译这段代码将产生如下错误：

Compiling this code will produce an error, as follows:

{{#include ../listings/ch03-common-programming-concepts/no-listing-23-statements-dont-return-values/output.txt}}

主要错误消息 mismatched types（类型不匹配）揭示了这段代码的核心问题。函数 plus_one 的定义表明它将返回一个 i32，但语句并不求值得出一个值，这由单元类型 () 表示。因此，没有返回任何内容，这与函数定义矛盾并导致错误。在此输出中，Rust 提供了一条消息来可能帮助纠正此问题：它建议删除分号，这将修复错误。

The main error message, mismatched types, reveals the core issue with this code. The definition of the function plus_one says that it will return an i32, but statements don’t evaluate to a value, which is expressed by (), the unit type. Therefore, nothing is returned, which contradicts the function definition and results in an error. In this output, Rust provides a message to possibly help rectify this issue: It suggests removing the semicolon, which would fix the error.