Глава 2. Структурирование кода в Rust

Создание простого файла Rust и его запуск.

Создание простого приложения при помощи Cargo.

Исполнение нашего приложения при помощи Cargo.

Управление зависимостями при помощи Cargo.

Применение корзины стороннего разработчика для упорядочения JSON.

Документирование нашего приложения при помощи Cargo.

Для этого создайте файл с названием hello_world.rs с необходимой функцией main, размещающей функцию println! с какой- то строкой, как мы это можем видеть здесь:

fn main() {
    println!("hello world");
}
 	   

После выполнения этого мы можем перейти к этому файлу и выполнить команду rustc:

rustc hello_world.rs
 	   

Данная команда скомпилирует этот файл в некий двоичный, который подлежит выполнению. Если мы выполнили компиляцию в Windows, мы можем запустить свой двоичный файл при помощи такой команды:

.\hello_world.exe
 	   

Когда мы выполнили компиляцию в Linux или Mac, мы можем запускать его следующей командой:

./hello_world.exe
 	   

Затем наша консоль должна выдать на печать определённую нами строку. Хотя это и может показаться полезным при построении обособленного файла, такой подход не рекомендуется для управления программами, распространяющимися на множество файлов. Более того, он даже не рекомендуется когда вы рассматриваете зависимости. И именно тут на помощь приходит Cargo. Cargo управляет всем - исполнением, тестированием, документированием, сборкой и зависимостями из одного места - при помощи нескольких простых команд.

В своём терминале перейдите туда, где вы желаете чтобы пребывало ваше приложение и создайте новый проект с названием wealth_manager следующим образом:

cargo new wealth_manager
		

Это создаст наше приложение со следующей структурой:

└── wealth_manage
    ├── .git
    ├── Cargo.toml
    ├── .gitignore
    └── src
        └── main.rs
		

Здесь мы можем видеть что Cargo собрал необходимую базовую структуру приложения, которая способна управлять компиляцией, работать с GitHub и управлять зависимостями прямо из одного места. Необходимые метаданные и зависимости нашего приложения определяются в соответствующем файле Cargo.toml.

Для выполнения команд Cargo с этим приложением, наш терминал должен пребывать в том же самом каталоге, что и файл Cargo.toml. Тот код, который мы намерены изменять и который составляет наше приложение располагается в соответствующем каталоге src. Нашей точкой входа для всего приложения выступает файл main.rs. В Python мы можем обладать множеством точек входа и мы поясним это в Главе 4, Сборка модулей pip в Python, в которой мы будем собирать чистые пакеты Python для самого первого раза. Если мы откроем свой файл .gitignore, мы должны обнаружить следующее:

/target
		

Это не ошибка; именно так выглядит чистый Rust. Всё что производит Cargo когда дело доходит до компиляции, документирования, кэширования и тому подобного, всё это сохраняется в каталоге target.

Прямо сейчас, всё что у нас есть, это наш файл main, который имеет вывод на печать консоли, сообщающий "hello world". Мы можем выполнить его при помощи такой команды:

cargo run
		

При помощи данной команды мы получаем в своём терминале следующий вывод:

Compiling wealth_manager v0.1.0 (/Users/maxwellflitton
/Documents/github/book_two/chapter_two/wealth_manager)

Finished dev [unoptimized + debuginfo] target(s) in 0.45s

Running 'target/debug/wealth_manager'

Hello, world!
		

Здесь мы видим что наше приложение было скомпилировано. После его компиляции постулируется что наш процесс компиляции был завершён.

Однако, мы должны заметить, что здесь также постулируется что наш завершённый процесс не оптимизирован за счёт отладочных сведений. Это означает, что наш скомпилированный продукт не настолько быстр, насколько это можно; однако он содержит средства отладки, если они понадобятся. Данный тип компиляции является быстрым по сравнению с оптимизированной версией и должен применяться при разработке приложения в противоположность промышленным средам реального времени. Затем мы увидим, что наш скомпилированный файл находится в target/debug/wealth_manager и он далее запускается, приводя в результате к выводу hello_world.rs.

Если мы желаем исполнить некий выпуск, мы просто исполняем такую команду:

cargo run --release
		

Она компилирует оптимизированную версию нашего прикладного приложения в каталоге ./target/release/ с исполняемым файлом wealth_manager. Если мы хотим только скомпилировать приложение без его исполнения, мы можем просто переключиться с команды run на build.

Разметить структуру файлов и папок.

Создать свои структуры Stock.

Привязать свою структуру Stock к соответствующему файлу main.

Воспользоваться модулем stocks в своём файле main.

Добавить код из другого модуля.

Мы можем выполнить свой модуль имеющим структуру, определяемую следующим образом:

├── main.rs
└── stocks
    ├── mod.rs
    └── structs
        ├── mod.rs
        └── stock.rs
		

Мы выбрали эту структуру для обеспечения большей гибкости; если нам требуется добавить дополнительные структуры, мы можем выполнить это в своём каталоге structs. Мы также можем добавить и прочие каталоги помимо своего каталога structs. Например, мы можем пожелать собрать механизм хранения данных для своих акций. Этого можно достичь добавив каталог storage в свой каталог stocks и применяя его во всём модуле по мере необходимости.

На данный момент мы просто хотим создать некую структуру акции в своём модуле stocks, импортировать его в свой файл main.rs и воспользоваться им. На первый шаг состоит в определении своей структуры Stock в файле stock.rs при помощи такого кода:

pub struct Stock {
    pub name: String,
    pub open_price: f32,
    pub stop_loss: f32,
    pub take_profit: f32,
    pub current_price: f32
}
		

Это выглядит знакомо, поскольку это та же самая структура Stock, которую мы определяли в своей предыдущей главе. Однако имеется лёгкое отличие. Нам следует заметить, что имеется ключевое слово pub перед определением этой структуры и определением каждого поля. Это обусловлено тем, что нам приходится объявлять их общедоступными (public) прежде чем мы сможем применять их вне этого файла. Это также применимо и к реализуемым в том же самом файле функциям, как это отображено в приводимом ниже коде:

impl Stock {
    pub fn new(stock_name: &str, price: f32) -> \
      Stock {
        return Stock{
            name: String::from(stock_name),
            open_price: price,
            stop_loss: 0.0,
            take_profit: 0.0,
            current_price: price
        }
    }
    pub fn with_stop_loss(mut self, value: f32) \
      -> Stock {
        self.stop_loss = value;
        return self
    }
    pub fn with_take_profit(mut self, value: f32) \
      -> Stock {
        self.take_profit = value;
        return self
    }
    pub fn update_price(&mut self, value: f32) {
        self.current_price = value;
    }
}
		

Теперь мы можем видеть, что у нас имеется общедоступная структура, которая доступна со всеми её функциями.

Теперь, когда наша структура доступна, мы можем просто применять её так, как если бы она была бы определена в том же самом файле следующим образом:

mod stocks;
use stocks::structs::stock::Stock;
fn main() {
    let stock: Stock = Stock::new("MonolithAi", 36.5);
    println!("here is the stock name: {}",\
      stock.name);
    println!("here is the stock name: {}",\
      stock.current_price);
}
		

Исполнение данного кода без всяких сюрпризов выдаёт нам:

here is the stock name: MonolithAi
here is the stock name: 36.5
		

Самое первое понятие, которое нам надлежит рассмотреть это доступ из файлов в том же самом каталоге. Для демонстрации этого мы можем сделать одноразовый пример построения функции печати в своих структурах. В новом файле со значением пути src/stocks/structs/utils.rs мы можем создать игрушечную функцию которая лишь выводит на печать что наш конструктор для соответствующей структуры сработал, как это показано в приводимом ниже коде:

pub fn constructor_shout(stock_name: &str) -> () {
    println!("the constructor for the {} is firing", \
      stock_name);
}
		

Затем мы объявляем в своём файле src/stocks/structs/mod.rs следующий код:

pub mod stock;
mod utils;
		

Необходимо отметить, что мы не превращаем его в общедоступный; мы просто объявляем его вместо этого. Ничто не запрещает нам превратить его в общедоступный; тем не менее, при подходе без общедоступности, мы делаем возможным доступ к нему только для файлов внутри текущего каталога src/stocks/structs/stock.rs.

Теперь мы хотим чтобы наша структура Stock выполняла доступ к нему в нашем конструкторе, что можно осуществить при помощи импорта в src/stocks/structs/stock.rs следующей строкой:

use super::utils::constructor_shout;
		

Если мы хотим переместить свою ссылку в соответствующий каталог src/stocks/, мы можем воспользоваться super::super. Мы можем соединять в цепочку столько super, сколько пожелаем, в зависимости от глубины своего дерева. Необходимо отметить, что мы можем выполнять доступ только к тому, что мы объявили в своём файле mod.rs в этом каталоге. В своём файле src/stocks/structs/stock.rs мы теперь можем воспользоваться функцией в нашем конструкторе при помощи такого кода:

pub fn new(stock_name: &str, price: f32) -> Stock {
    constructor_shout(stock_name);
    return Stock{
        name: String::from(stock_name),
        open_price: price,
        stop_loss: 0.0,
        take_profit: 0.0,
        current_price: price
    }
}
		

Теперь, когда мы запустим своё приложение, мы получим в своём терминале приводимый ниже вывод на печать:

the constructor for the MonolithAi is firing
here is the stock name: MonolithAi
here is the stock name: 36.5
		

Мы можем видеть, что наша программа выполняется в точности так же, причём с соответствующей дополнительной строкой из функции util, которую мы импортировали. Если мы создадим ещё один модуль, мы сможем получить доступ к своему модулю stocks, потому как наш модуль stocks определён в основном файле main.rs.

Выполнить структуру схемы своего модуля при помощи правильных файлов.

Создать некое упорядочение для своих различных типов заказов.

Построить структуру заказа.

Установить корзину (crate) chrono, необходимую для объектов datetime.

Создать конструктор заказа, который применяет корзину chrono.

Создать динамические значения для этой структуры.

Создать интерфейс закрытия заказа.

Создать интерфейс открытия заказа.

Воспользоваться интерфейсами заказа в своём файле main.

Здесь мы разрешаем себе доступ к структуре stock только через структуру order. И снова, имеется множество способов подхода к этой задаче, что является демонстрацией того, как создавать интерфейсы Rust. Чтобы добиться этого в нашем коде, у нас имеется определяемая ниже файловая структура:

├── main.rs
└── stocks
    ├── enums
    │   ├── mod.rs
    │   └── order_types.rs
    ├── mod.rs
    └── structs
        ├── mod.rs
        ├── order.rs
        └── stock.rs
		

Прежде всего мы можем определить свои типы enum (нумерации) заказов в своём файле enums/order_types.rs при помощи такого кода:

pub enum OrderType {
    Short,
    Long
}
		

Мы будем пользоваться ими в своих заказах и интерфейсах. Чтобы сделать доступным этот тип нумерации для всего остального модуля нам придётся объявить их в своём файле enums/mod.rs при помощи следующего кода:

pub mod order_types;
		

Теперь, когда мы построили свой тип enum, самое время пустить его в работу. Теперь мы можем построить свою структуру ордера в файле stocks/structs/order.rs с приводимым ниже кодом:

use chrono::{Local, DateTime};
use super::stock::Stock;
use super::super::enums::order_types::OrderType;

pub struct Order {
    pub date: DateTime,
    pub stock: Stock,
    pub number: i32,
    pub order_type: OrderType
}
		

Здесь мы пользуемся корзиной chrono для определения времени размещения этого ордера; мы также должны указать для каких акций предназначен этот заказ, значение числа покупаемых акций, а также тип заказа. Мы должны не забыть определить свою зависимость chrono в нашем файле Cargo.toml следующим кодом:

[dependencies]
serde="1.0.117"
serde_json="1.0.59"
chrono="0.4.19"
		

Основная причина по которой мы оставляем свою структуру stock обособленной от структуры order состоит в разрешении гибкости. Например, могут иметься прочие вещи, которые мы можем выполнять со своими данными акций, которые не связаны с заказом. Мы можем пожелать собрать некую структуру, которая размещает акции в определённом списке отслеживания пользователя, а этот пользователь в реальности ничего не покупает, а всего лишь желает отслеживать значение доступности акций.

Тем не менее, существуют и иные варианты применения данных акции. Учитывая это, мы можем видеть, что сохраняя необходимые сведения и методы относительно акции в некой индивидуальной структуре stock помогает не только снижать объём кода, который нам приходится писать когда мы добавляем дополнительные функциональные возможности, но также и стандартизировать имеющиеся для акции сведения. Это также упрощает нам сопровождение всего кода. Когда мы добавляем или удаляем поле, либо изменяем метод для данных акции, нам приходится изменять их лишь в одном месте, а не по множеству расположений. Наш конструктор для нашей структуры order может быть выполнен в том же самом файле при помощи следующего кода:

impl Order {
    pub fn new(stock: Stock, number: i32, \
      order_type: OrderType) -> Order {
      let today: DateTime<Local> = Local::now();
        return Order{date: today, stock, number, \
          order_type}
    }
}
		

Здесь мы создали структуру Order, получая параметры stock, number и order_type и создавая структуру datetime.

Поскольку наш заказ сосредоточен на логике относительно цен этого заказа, поскольку он размещает значение числа акций, доставлявшихся в этом заказе, в своём блоке impl мы можем построить своё текущее значение этого заказа таким кодом:

	pub fn current_value(&self) -> f32 {
        return self.stock.current_price * self \
          .number as f32
    }
		

Следует отметить, что в качестве параметра нам приходится применять &self вместо простого использования self. Это позволяет нам применять данную функцию много раз. Если бы этот параметр не был бы ссылкой, тогда нам приходилось бы перемещать свою структуру в эту функцию. Мы бы не были способны вычислять соответствующее значение множество раз и это было бы полезным делать только если соответствующий тип не Copy.

Мы также можем построить на этой функции вычисление текущей прибыли в блоке impl при помощи приводимого ниже кода:

    pub fn current_profit(&self) -> f32 {
        let current_price: f32 = self.current_value();
        let initial_price: f32 = self.stock. \
          open_price * self.number as f32;

        match self.order_type {
          OrderType::Long => return current_price -\
            initial_price,
          OrderType::Short => return initial_price -\
            current_price
        }
    }
		

Здесь мы получаем текущую и начальную стоимости. Затем мы сопоставляем тип заказа, поскольку он меняет то как вычисляется прибыль. Теперь, когда наша структура завершена, нам придётся убедиться что эта структура доступна через её определение в нашем файле stocks/structs/mod.rs при помощи следующего кода:

pub mod stock;
pub mod order;
		

Теперь мы готовы к созданию своих интерфейсов. Чтобы собрать наш интерфейс в своём файле stocks/mod.rs, нам вначале придётся импортировать всё что нам требуется, как это показано в приводимом далее коде:

pub mod structs;
pub mod enums;

use structs::stock::Stock;
use structs::order::Order;
use enums::order_types::OrderType;
		

Теперь, когда у нас имеется всё что нужно для построения нашего интерфейса, мы можем собрать свой интерфейс закрытия заказа при помощи такого кода:

pub fn close_order(order: Order) -> f32 {
    println!("order for {} is being closed", \
      &order.stock.name);
    return order.current_profit()
}
		

Это достаточно простой интерфейс; мы можем сделать больше, например вызов базы данных или API, однако для данной демонстрации нам достаточно выдать на печать значение подлежащей продаже акции и вернуть значение полученной нами текущей прибыли. Имея в виду это, мы можем собрать более сложный интерфейс открывая некий заказ в том же самом файле при помощи приводимого далее кода:

pub fn open_order(number: i32, order_type: OrderType,\
                  stock_name: &str, open_price: f32,\
                  stop_loss: Option<f32>, \
                    take_profit: Option<f32>) -> \
                      Order { \
    println!("order for {} is being made", \
      &stock_name);              
    let mut stock: Stock = Stock::new(stock_name, \
      open_price);
    match stop_loss {
        Some(value) => stock = \
          stock.with_stop_loss(value),
        None => {}
    }
    match take_profit {
        Some(value) => stock = \
          stock.with_take_profit(value),
        None => {}
    }
    return Order::new(stock, number, order_type)
}
		

Здесь мы получаем все необходимые нам параметры. Мы также представили тип аргумента Option<f32>, который реализуется как некий нумерующий тип. Это позволяет нам передавать передавать значение None. Затем мы создаём изменяемую акцию (так как стоимость может меняться и нам придётся обновлять её), а далее проверяем предоставлено ли значение stop_loss; если это так, мы затем добавляем останов потерь для этой акции. После этого мы проверяем предоставлено ли значение take_profit, обновляя им свою акцию в таком случае.

Теперь, когда мы собрали все свои интерфейсы, всё что нам требуется, это воспользоваться ими в своём файле main.rs. В этом файле main нам необходимо импортировать все требуемые структуры и интерфейсы для их применения при помощи следующего кода:

mod stocks;

use stocks::{open_order, close_order};
use stocks::structs::order::Order;
use stocks::enums::order_types::OrderType;
		

В своей функции main мы можем начать помещать эти интерфейсы в работу, создавая новые изменяемые заказы следующим кодом:

println!("hello stocks");
let mut new_order: Order = open_order(20, \
    OrderType::Long, "bumper", 56.8, None, None);
		

Здесь мы устанавливаем take_profit и stop_loss в None, но мы можем добавить их в случае необходимости. Для прояснения того что мы привнесли, мы можем выдать на печать свои текущие значение и прибыль таким кодом:

println!("the current price is: {}",
    &new_order.current_value());
println!("the current profit is: {}",
    &new_order.current_profit());
		

Далее мы получаем некие движения на ранке акций, которые можно имитировать обновлением значения стоимости и выводом на печать полученного значения наших инвестиций при каждом изменении при помощи следующего кода:

new_order.stock.update_price(43.1);
println!("the current price is: {}", \
    &new_order.current_value());
println!("the current profit is: {}", \
    &new_order.current_profit());

new_order.stock.update_price(82.7);
println!("the current price is: {}", \
         &new_order.current_value());
println!("the current profit is: {}", \
         &new_order.current_profit());
		

Теперь у нас имеется некая прибыль и мы продадим свои акции чтобы закрыть имеющийся заказ и выведем на печать полученную прибыль таким кодом:

let profit: f32 = close_order(new_order);
println!("we made {} profit", profit);
		

Теперь наши интерфейсы, модуль и файл main собраны. Запуск команды Cargo run снабдит нам с таким выводом на печать:

hello stocks
the constructor for the bumper is firing
the current price is: 1136
the current profit is: 0
the current price is: 862
the current profit is: -274
the current price is: 1654
the current profit is: 518
order for bumper is being closed
we made 518 profit
		

Импортировать все необходимые корзины.

Собрать все входные данные в своём окружении.

Обработать свои входные данные при помощи заказа.

Теперь, когда добавлена наша корзина rand, мы можем добавить некие дополнительный импорт, который нам требуется в основном файле main.rs следующим кодом:

use std::env;
use rand::prelude::*;
use std::str::FromStr;
		

Для получения передаваемых в Cargo параметров мы применяем env. Из prelud в корзине rand мы импортируем всё, поэтому мы можем генерировать случайные числа, к тому же мы импортируем признак (trait) FromStr, а потому мы можем преобразовывать строки, передаваемые из параметров командной строки в числа.

В своей функции main мы сперва собираем все переданные из соответствующей командной строки параметры таким кодом:

let args: Vec<String> = env::args().collect();
let action: &String = &args[1];
let name: &String = &args[2];
let amount: i32 = i32::from_str(&args[3]).unwrap();
let price: f32 = f32::from_str(&args[4]).unwrap();
		

Мы устанавливаем, что мы намерены собрать все параметры командной строки в векторе строк. Мы делаем это по той причине, что практически всё можно представлять строкой. Затем мы определяем все необходимые нам параметры. Следует отметить, что мы начинаем с индекса 1 вместо 0. Это обусловлено тем, что индекс 0 заполнен самой командой run. Мы также можем заметить, что мы, когда нам требуются строки непосредственно распакованными, мы преобразовываем их в числа. Это слегка рискованно; в идеале мы должны устанавливать соответствие полученного результата из функции from_str и снабжать своего пользователя лучшими сведениями при надлежащем построении промышленного инструмента командной строки.

Теперь, когда у нас имеется всё что нам необходимо, мы создаём новый заказ при помощи собранных нами сведений при помощи приводимого ниже кода:

let mut new_order: Order = open_order(amount, \
    OrderType::Long, &name.as_str(), price, \
        None, None);
		

Мы создаём новый заказ каждый раз даже если это продажа, так как у нас нет хранилища и нам необходимо иметь все свои структурированные данные и логику относительно своей позиции акции. Затем мы устанавливаем соответствие своим действиям. Если мы хотим продать свои акции, мы вырабатываем новую стоимость для этой акции перед продажей. С учётом этого мы можем обнаружить остались ли мы в прибыли или нет при помощи такого кода:

match action.as_str() {
    "buy" => {
        println!("the value of your investment is:\
          {}", new_order.current_value());
    }
    "sell" => {
        let mut rng = rand::thread_rng();
        
        let new_price_ref: f32 = rng.gen();
        let new_price: f32 = new_price_ref * 100 as \
          f32;
        new_order.stock.update_price(new_price);
        let sale_profit: f32 = close_order(new_order);
        println!("here is the profit you made: {}", \
            sale_profit);
    }
    _ => {
        panic!("Only 'buy' and 'sell' actions are \
          supported");
    }
}
		

Следует отметить, что у нас имеется _ в конце выражения соответствия. Это происходит по той причине, что теоретически строка может быть любой, а Rust безопасный язык. Это не позволит нам скомпилировать код, если мы не будем учитывать каждый результат. _ это универсальный шаблон. Если созданы не все шаблоны сопоставления, то выполняется он. Для нашего случая мы просто возбуждаем ошибку, заявляя, что поддерживаются только продажи и покупки.

Для запуска нашей программы мы выполняем такую команду:

cargo run sell monolithai 26 23.4
		

Её исполнение снабдит нас следующим выводом:

order for monolithai is being made
order for monolithai is being closed
here is the profit you made: 1825.456
		

Значение прибыли может отличаться, поскольку вырабатываемое нами число случайное.

Продолжая писать код как мы документируем его?

Почему важна единая концепция изоляции модулей?

Как мы позволяем своим модулям сохранять преимущества изолированных модулей?

Как мы управляем зависимостями в своём приложении?

Как мы можем гарантировать, что в выражении сопоставления учитываются все результаты, при том, что теоретически существует бесконечное число результатов, таких как сопоставление различных строк?

Допустим, у меня имеется структура с названием SomeStruct в каком- то файле some_file/some_struct.rs. Как мы можем сделать её доступной вне того каталога, в котором она расположена?

Допустим, мы изменили своё мнение относительно нашей структуры SomeStruct из 6 вопроса и мы хотим чтобы она стала доступной только в нашем каталоге some_file/. Как это сделать?

Как мы можем выполнить доступ к своей структуре SomeStruct в соответствующем файле some_file/another_struct.rs?

Наши строки документации способны поддерживать Markdown в то время как мы строим свои структуры и функции. Поскольку это Markdown, мы можем документировать способы реализации структур или функций. Когда мы пользуемся Visual Studio Code, это также повышает нашу производительность, так как простое наведение указателя мыши на функцию или структуру открывает их документацию.

Ограничение наших модулей одной концепцией повышает гибкость приложения, позволяя нам нарезать и изменять модули по мере необходимости.

Чтобы наши модули были изолированы, нам нужно, чтобы интерфейсы модуля оставались теми же самыми; это означает, что мы можем изменить логику внутри модуля, не изменяя ничего в остальной части приложения. Если мы удалим свой модуль, нам нужно будет искать только реализации интерфейса во всем приложении, а не реализацию всех функций и структур в модуле.

Мы управляем зависимостями в файле Cargo.toml. Простое исполнение Cargo установит все имеющиеся у нас требования при компиляции перед исполнением.

Мы можем учитывать всё, перехватывая что угодно что не удовлетворяет всем нашим соответствиям. Это выполняется через реализацию шаблона _ в самом конце нашего выражения соответствия, выполняя прикреплённый к нему код.

Мы можем сделать его общедоступным, написав pub mod some_struct; в своём файле some_file/mod.rs.

Написав mod some_struct; в своём файле some_file/mod.rs мы превращаем его в общедоступный только в каталоге some_file/.

Мы можем получить доступ в SomeStruct, набрав в файле some_file/another_struct.rs use super::some_struct::SomeStruct;.