A Rust crate providing utility functions and macros.

Overview

介绍

此库提供四类功能:异常处理、http post收发对象、格式转换、语法糖。

Cargo.toml 里添加如下依赖项

[dependencies.xuanmi_base_support]
git = "https://github.com/taiyi-research-institute/xuanmi_base_support"
branch = "main"

如果你在中国大陆,git 链接可以改成

ssh://[email protected]/taiyi-research-institute/xuanmi_base_support

如果你需要运行单元测试,推荐使用如下命令。

cargo test -- --show-output

异常处理

当你使用此库提供的异常处理机制时,笔者推荐你养成如下几个习惯。按照这样的习惯来处理异常,你将得到类似于Java Exception的报错信息。

  1. 如果你自己写的函数有可能执行失败,那么这个函数的返回类型应该指定为 Outcome<T>
  2. 如果你调用别人的函数,且该函数有可能失败,那么你要在函数调用的后面跟 .catch(name, context)? 。 这是用来取代.unwrap().expect() 的。
  3. 把你写过的 panic!(...); 替换成 throw!(...); 。类似地,把你写过的 assert!(cond, ...); 替换成 if cond { throw!(...); }
  4. 给Exception起名时,建议传符号,不建议传字符串字面量。

例1:调用别人的函数,该函数有可能失败。要点:Outcome, catch

#[macro_use] use xuanmi_base_support::*; 
use serde_json;

pub fn objectToJson<T>(
    obj: &T
) -> Outcome<String> where T: Serialize {
    let json: String = serde_json::to_string(obj)
    .catch( // 取代unwrap
        // EXN是模块名. 我在模块EXN里定义了许多Exception名称
        EXN::SerializationException, 
        // 上下文信息
        &format!("Failed to convert object of type `{}` to JSON string", std::any::type_name::<T>()),
    )?;
    Ok(json)
}

例2:你写一个可能失败的函数。要点:Outcome, catch

#[macro_use] use xuanmi_base_support::*; 

fn div() -> Outcome<f64> {
    let (a, b): (f64, f64) = (1.0, 0.0);
    let eps: f64 = 1.0 / 4096.0;
    if b.abs() < eps {
        throw!( // 取代panic或assert
            name=EXN::ArithmeticException,
            ctx=&format!("Cannot divide a={:.4} by b={:.4}", a, b)
        );
    } else {
        return Ok(a/b);
    }
}

关于宏 throw! ,你只能给它传零对到若干对键值参数。通过传递这些参数,你可以定制报错信息。支持的参数有

  • name - 错误的名称。笔者喜欢仿照Java Exception的名称。你也可以用错误代码。
  • ctx, context - 详细的报错信息。通常需要配合Rust语言提供的 format! 宏。
  • src, cause - 错误对象,可以是任何实现了 std::error::Error 的对象。用于给已有的错误对象(比如 match 里的 Err(e) 里的 e)再套一层。

除非你清楚此库异常处理的原理,否则不建议设定以下参数。

  • file - 源码文件的路径。不传则为 throw! 被调用的文件路径。
  • line - 源码行号。不传或传0则为 throw! 被调用的行号。
  • col, column - 源码列号。不传或传0则为 throw! 被调用时,首字母左侧光标的偏移量。

http post收发对象

此库提供了 http_post 函数。这个函数把一个Rust对象序列化成JSON,作为POST请求体,发送给一个URL;之后,这个函数把响应体当成JSON,反序列化成另一个Rust对象。注意:(1)这个函数每1000ms重试一次,一共重试3次,即最多请求4次;(2)服务端对 content-type 要么不过滤, 要么允许 application/json .

例子:

首先定义收发结构体。结构体需实现Clone, Serialize, Deserialize。

use serde::{Serialize, Deserialize};

#[derive(Debug, Clone, Serialize, Deserialize)]
struct MyRequest {
    uname: String,
    email: String,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
struct MyResponse {
    a: String,
    b: String,
}

定义好结构体就可以收发了。

#[macro_use] use xuanmi_base_support::*;

fn test_http_post() -> Outcome<MyResponse> {
    let req = MyRequest {
        uname: "xuanmi".to_string(),
        email: "[email protected]".to_string(),
    };
    let url = "http://localhost:50000/test";
    let resp: MyResponse = http_post(url, &req).catch(
    	name=EXN::HttpPostException,
    	ctx=&format!("Failed to post to {}", url)
    )?;
    // do something else ...
    Ok(resp)
}

格式转换

To be continued...

语法糖

To be continued...

You might also like...
proc-macro to help with using surrealdb's custom functions

SurrealDB Functions This is a proc-macro crate that given a path to a .surql file or a folder of .surql files, will parse DEFINE FUNCTION fn::s inside

DWARF packaging utility, written in Rust, supporting GNU extension and DWARF 5 package formats.

thorin thorin is an DWARF packaging utility for creating DWARF packages (*.dwp files) out of input DWARF objects (*.dwo files; or *.o files with .dwo

The utility is designed to check the availability of peers and automatically update them in the Yggdrasil configuration file, as well as using the admin API - addPeer method.

Yggrasil network peers checker / updater The utility is designed to check the availability of peers and automatically update them in the Yggdrasil con

Modern Rust utility library delivering modularity, performance & extras; or simply Rust version of Lodash

Lorust - API Documentation Lorust is the Rust version of Lodash, which is a modern Javascript utilty library delivering modularity, performance & extr

Elton is a benchmark utility written in rust aimed to be used to benchmark HTTP calls.

Elton Elton is an HTTP Benchmark utility with options to be used within an HTTP interface. Installation Elton is currently available via Docker or by

A small utility for modifying ELF shared library loading order.

elfpromote A small utility for modifying ELF shared library loading order. Usage $ cargo install elfpromote $ ldd blueboat_server linux-vdso.s

Omeglib, a portmanteau of "omegle" and "library", is a crate for interacting with omegle, simply and asynchronously

Omeglib, a portmanteau of "omegle" and "library", is a crate for interacting with omegle, simply and asynchronously. It is intended to suit one's every requirement regarding chat on omegle.

Rust on ESP32 STD "Hello, World" app. A "Hello, world!" STD binary crate for the ESP32[XX] and ESP-IDF.

Rust on ESP32 STD "Hello, World" app A "Hello, world!" STD binary crate for the ESP32[XX] and ESP-IDF. This is the crate you get when running cargo ne

Rust-idiomatic, compliant, flexible and performant BIP21 crate

Rust implementation of BIP21 Rust-idiomatic, compliant, flexible and performant BIP21 crate. About Important: while lot of work went into polishing th

Owner
null
A query-building & utility crate for SurrealDB and its SQL querying language that aims to be simple

Surreal simple querybuilder A simple query-builder for the Surreal Query Language, for SurrealDB. Aims at being simple to use and not too verbose firs

Thibault H 11 Dec 30, 2022
Attribute for defining `macro_rules!` macros with proper visibility and scoping

macro-vis This crate provides an attribute for defining macro_rules! macros that have proper visibility and scoping. The default scoping and publicity

null 2 Aug 29, 2022
Linux daemon to bind keys and macros to your controller's buttons

makima Makima is a daemon for Linux to bind your controller's buttons to key sequences and macros. Features: Configure your keybindings through a simp

null 48 Jun 14, 2023
Learn to write Rust procedural macros [Rust Latam conference, Montevideo Uruguay, March 2019]

Rust Latam: procedural macros workshop This repo contains a selection of projects designed to learn to write Rust procedural macros — Rust code that g

David Tolnay 2.5k Dec 29, 2022
Lightweight parsing for Rust proc macros

Lightweight parsing for Rust proc macros Venial is a WIP parser for Rust proc macros. When writing proc macros that need to parse Rust code (such as a

Olivier FAURE 148 Dec 30, 2022
Proc-macros for generating icons from the Iconify API

iconify-rs This crate provides a macro to embed SVGs from Iconify. For a list of icons, see Iconify Icon Sets. ?? Usage let svg = iconify::svg!("mdi:h

Matthew Taylor 5 Jul 9, 2023
Tiny macros for bailing on failure

tiny_bail Bailing is an error-handling pattern that takes the middle path between unwrap and ?: Compared to unwrap: Bail will return, continue, or bre

Ben Frankel 22 Sep 10, 2024
A library for extracting #[no_mangle] pub extern "C" functions (https://docs.rust-embedded.org/book/interoperability/rust-with-c.html#no_mangle)

A library for extracting #[no_mangle] pub extern "C" functions In order to expose a function with C binary interface for interoperability with other p

Dmitrii - Demenev 0 Feb 17, 2022
Generate rust structs & query functions from diesel schema files

dsync A utility to generate database structs and querying code from diesel schema files. Primarily built for create-rust-app. Currently, it's more adv

Haris 20 Feb 12, 2023
Functions for mapping plaintexts to a u64 while preserving sort order

ore_encoding.rs This is a companion package to ore.rs that can generate and manipulate u64 plaintexts before they are encrypted by ore.rs. Being able

CipherStash 2 Dec 14, 2022