Scala on boboboker~

泛型

Fri, 16 May 2025 00:00:00 +0800

泛型

泛型(Generic)是非常重要的语言功能，广泛应用于各种项目、工具、框架。
本文主要关注泛型的应用，由浅入深介绍和讨论能力和限制，给出相关示例来演示应用。

演示代码语言/平台采用最新LTS或主流支持版本，详细情况如下：

C# 12 on .NET 8 (LTS)

F# 8 on .NET 8 (LTS)

Java 21 on JDK 21 (LTS)

Scala 3.3.x (LTS) on JDK 21 (LTS)

Scala 2.13.x on JDK 21 (LTS)

Python 3.13.x

.NET版本支持策略参考官方文档: .NET Support Policy; C#和F#随.NET一同发布/更新

Scala与JDK兼容情况可参考官方介绍: JDK Compatibility
Scala 2.x 维护计划在Scala 2 maintenance plans及Scala development guarantees中有介绍，简言之2.13将持续维护，2.12将在sbt 1广泛应用期间持续维护
Scala 2.13相对与2.12的变化可参考: Migrating a Project to Scala 2.13’s Collections, Scala 2.13.0 is now available!, Releases / Scala 2.13.0
Scala 3相对于2的变化可参考: Scala 3 Migration Guide

Python的版本支持情况可参考官方介绍: Status of Python versions

基本语法

本节简要介绍泛型在各语言中的基本使用。

C#

官方文档: \

Generics in .NET

C# specifications / Types / Constructed types

Generic classes and methods

……

泛型接口、泛型类和泛型方法

如下代码演示了泛型接口、泛型类、泛型方法(实例方法及静态方法)的定义和调用。\

Generic Classes (C# Programming Guide)

Generic Interfaces (C# Programming Guide)

Generic methods (C# programming guide)

// ==========[定义泛型]==========

// 定义泛型接口
interface IWritable<T>
{
    void Write(T value);
}
interface IReadable<T>
{
    T Read();
    // 接口自带默认实现
    string ReadString() => Read().ToString();
}

// 定义泛型类(并实现泛型接口)
class Response<T> : IReadable<T>, IWritable<T>
{
    public int Code { get; set; }
    public string Message { get; set; }
    // Data属性是个泛型属性
    public T Data { get; set; }

    // 构造器方法
    public Response() { }
    public Response(int code, string message, T data) : this()
    {
        this.Code = code;
        this.Message = message;
        this.Data = data;
    }
    // 解构方法
    public void Deconstruct(out int code, out string message, out T data)
    {
        code = Code;
        message = Message;
        data = Data;
    }

    // 实现泛型接口中定义的方法
    public T Read() => Data;
    public void Write(T value) => Data = value;

    // 定义泛型实例方法
    public bool TryRefreshData<U>(U data)
    {
        if (data is T t)
        {
            this.Data = t;
            return true;
        }
        return false;
    }

    // 尽量避免在泛型类中定义静态方法，调用相对比较麻烦
    // 定义泛型静态方法
    public static Response<U> Success<U>(U data)
        => new(0, "success", data);
    // 定义静态方法
    public static Response<string> Failed(string message)
        => new(1, message, "failed");
}

// 定义工具类
// C#中，泛型静态方法最好放在单独的工具类中，可以直接以
class ResponseHelper
{
    // 定义泛型静态方法
    public static Response<T> Success<T>(T data)
        => new(0, "success", data);
    public static Response<string> Failed(string message)
        => new(1, message, "failed");
}

// 定义(静态)扩展类
static class ResponseExtension
{
    // 定义泛型扩展方法
    public static Response<T> Copy<T>(this Response<T> response)
        => new(response.Code, response.Message, response.Data);
    // 定义泛型扩展方法
    public static bool IsSuccess<T>(this Response<T> response)
        => response.Code == 0;
}

// ==========[使用泛型]==========
// 初始化对象(调用构造器)
var response = new Response<string>(0, "success", "data");
// 初始化对象(属性初始化)
var response = new Response<string>
{
    Code = 0,
    Message = "success",
    Data = "data"
};
// 初始化对象(new表达式)
Response<string> response = new(0, "success", "data");
// 解构对象
var (code, _, data) = response;

// 泛型方法调用时，编译器可以从参数中推断类型，因此一般无需声明类型

// 调用泛型实例方法
response.TryRefreshData(123);
// 调用泛型实例方法(声明类型)
response.TryRefreshData<short>(123);

// 调用静态泛型方法
// 调用泛型类中的静态方法时，必须要声明泛型类的具体类型(泛型静态方法的类型一般无需声明)
var response = Response<string>.Success<short>(123);
// 调用普通工具类中的静态方法(泛型静态方法的类型一般无需声明)
var response = ResponseHelper.Success<short>(123);

// 调用泛型扩展方法(与实例方法调用语法一致)
var success = response.IsSuccess();
var copy = response.Copy();

泛型接口、泛型类、泛型方法算是面向对象编程中对泛型最基本的应用。
此外泛型抽象类并未因泛型而新增特殊之处，其本身的功能及限制只是因为它是“抽象类”而非“泛型”，因此代码中并未演示。

泛型委托和泛型事件

委托和事件C#独有的语言功能，两者皆支持泛型，此处演示相关应用。相关详细概念请参考官方文档。

Generic Delegates (C# Programming Guide)

Delegates (C# Programming Guide)

Events (C# Programming Guide)

// 定义泛型委托
delegate T BiOp<T>(T a, T b);

// 使用泛型委托
BiOp<int> add = (a, b) => a + b;
var c = add(1, 2);

class Singleton<T>
{
    // 定义事件
    public event EventHandler<T> ValueChanged;

    private T _value;
    public T Value 
    { 
        get => _value;
        set
        {
            if (!EqualityComparer<T>.Default.Equals(Value, value))
            {
                _value = value;
                OnValueChanged(value);
            }
        }
    }

    protected virtual void OnValueChanged(T value)
    {
        // 触发事件
        ValueChanged?.Invoke(this, value);
    }
}

// 初始化对象
var singleton = new Singleton<int>();
// 订阅事件(多个事件处理程序)
singleton.ValueChanged += (_, i) => Console.WriteLine($"int = {i}");
// 赋值&触发事件
singleton.Value = 1;
// 重复赋值&不触发事件
singleton.Value = 1;

事件本质上是特殊类型的委托。对两者的深入探讨请参考官网文档。、

Introduction to delegates

Introduction to events

Distinguishing Delegates and Events

泛型数组

Generics and Arrays (C# Programming Guide)

泛型数组本身没什么特殊，此处需要特别注明的是一维数组自动实现IList<T>接口，这有助于实现一个泛型方法对数组或其他集合进行遍历。
但要注意自动实现的IList<T>接口仅支持数据读取，不能用于从数组中增删元素(会抛出异常)。

// 直接以集合初始化语法定义并初始化数组和List
int[] array = [1, 2, 3, 4, 5];
List<int> list = [1, 2, 3, 4, 5];

// 以一致的方式访问(读取)数组和List
ProcessItems(array);
ProcessItems(list);

static void ProcessItems<T>(IList<T> list)
{
    // 数组对象调用IsReadOnly返回True,List对象会返回False
    Console.WriteLine("IsReadOnly returns {0} for this collection.", list.IsReadOnly);

    // 对数组对象调用Insert/RemoveAt方法会导致抛出异常
    //list.RemoveAt(4);

    foreach (T item in list)
    {
        Console.Write(item?.ToString() + " ");
    }
    Console.WriteLine();
}

F#

TBD

Java

泛型约束

泛型约束声明了类型参数预期的能力，声明约束后可以安全地调用支持的操作。

C#

Constraints on type parameters (C# Programming Guide)

C#具备种类丰富的泛型约束，下方列表中对各种类型进行简要介绍。

泛型约束	简介
`where T : struct`	`T`必须是不可为NULL的值类型(Value Type)(可以是`record struct`类型)。由于所有值类型必定存在可用的无参构造器，因此这也隐含声明`new()`约束。 `struct`约束不能与`new()`及`unmanaged`约束组合使用。
`where T : class`	`T`必须是引用类型(Reference Type)。 `T`可以是类、记录类(record class)、接口、委托、数组。在允许为NULL上下文(nullable context)中，`T`必须是不可为NULL的引用类型。
`where T : class?`	`T`必须是引用类型(Reference Type)，可以是允许为NULL的引用类型，也可以是不允许为NULL的引用类型。 `T`可以是类、记录类(record class)、接口、委托、数组。
`where T : notnull`	`T`必须是不可为NULL的类型。 `T`可以是不可为NULL的引用类型、不可为NULL的值类型。
`where T : unmanaged`	`T`必须是不可为NULL的非托管类型(Unmanaged Type)。 `unmanaged`约束隐含声明`struct`，不能与`struct`及`new()`约束组合使用。注：非托管类型包括内置值类型及布尔类型、枚举类型、指针类型、成员都是非托管类型的元组(tuple)和结构(struct)类型。但该约束依然不允许指针和可为NULL的非托管类型。
`where T : new()`	`T`必须有公开的无参构造器。当与其他约束组合使用时，`new()`约束必须放在最后。 `new()`约束不能与`struct`及`unmanaged`约束组合使用。
`where T : <class name>`	`T`必须是给定的类或继承自给定的类。在允许为NULL上下文(nullable context)中，`T`必须是不可为NULL的引用类型。
`where T : <class name>?`	`T`必须是给定的类或继承自给定的类。在允许为NULL上下文(nullable context)中，`T`可以是允许为NULL的引用类型，也可以是不允许为NULL的引用类型。
`where T : <interface name>`	`T`必须是给定的接口或实现了给定的接口。可以声明多个接口约束；约束中给定的接口也可以是泛型接口。在允许为NULL上下文(nullable context)中，`T`必须是实现给定接口的不允许为NULL的类型。
`where T : <interface name>?`	`T`必须是给定的接口或实现了给定的接口。可以声明多个接口约束；约束中给定的接口也可以是泛型接口。在允许为NULL上下文(nullable context)中，`T`必须是实现给定接口的可为NULL引用类型、不可为NULL的引用类型、值类型。`T`不可以是允许为NULL的值类型。
`where T : U`	`T`必须是类型参数`U`给定的类型或继承自给定类型。在允许为NULL上下文(nullable context)中，若`U`是不允许为NULL的引用类型，则`T`也必须是不可为NULL的引用类型；若`U`是允许为NULL的引用类型，则不限制`T`是否可为NULL。
`where T : default`	`T`必须未声明`struct`或`class`约束。该约束仅在显式实现接口方法或重写方法时可用，用于声明期望实现/重写的是`T`未被约束的方法。
`where T : allows ref struct`	该反约束允许`T`是`ref struct`类型。 `T`可能是`ref struct`实例，泛型类型和方法必须遵循引用安全规则(ref safety rules)。 C# 13.0+可用

某些约束是互斥的，某些约束必须遵循特定的顺序。

struct/class/class?/notnull/unmanaged约束至多允许一个，且必须是第一个约束；
基类约束(where T : Base/where T : Base?)至多允许一个，使用where T : Base?支持可为NULL的基类，基类约束不能与struct/class/class?/notnull/unmanaged约束组合使用；
不允许同时声明单个接口的可NULL和不可NULL形式(where T : I1, I1? ×; where T : I1, I2? √)；
new()约束不能与struct/unmanaged约束组合使用；若存在new()约束，其必须位于约束的最后(反约束可以放在它后面)；
default约束只能用于方法重写和显式实现接口方法场景，且不能与struct/class约束组合使用；
反约束allows ref struct不能与class/class?约束组合使用，且必须跟在所有约束的后面。

部分约束有如下注意事项。\

使用class约束时避免使用比较操作符==/!=。这组操作符只比较引用是否相等，不进行值比较。该行为不会因具体类型是否重载比较操作符而变化，因为编译时仅能得知类型是引用类型，必须调用对所有引用类型都合法有效的实现。若要在泛型代码中进行值比较，请使用where T : IComparable<T>或where T : IEquatable<T>约束并为实际类型实现相关接口。
若类型参数没有任何约束(例如SampleClass<T>{}中的T)称为未绑定类型(unbounded type parameter)，应当遵循如下规则：
- 不能使用比较操作符==/!=，因为不能保证实际类型支持该操作符；
- 可以显式转换为任何接口类型，也可以转换成System.Object类型(或者由System.Object转换成T)；
- 可以与null进行比较(T是值类型时会返回false)
notnull约束用以声明类型参数将约束为不可为NULL的值类型/引用类型，违反notnull约束时，编译器只会生成警告，不会报告错误。notnull约束仅在可空代码上下文中生效，若在忽略可空性的代码上下文使用，违反约束时编译器不会生成任何警告或错误。

以下对部分约束进行详细解释及代码演示。

泛型约束常规应用

// 单个类型参数的泛型约束
struct Container<T> where T : struct
{
    public T Value { get; set; }
}

// 多个类型参数的泛型约束(各自约束互不干涉)
class Container<K, V>
    where K : struct
    where V : class, new()
{
    // ...
}

// 类型参数作为约束
class SampleClass<T, U, V> where T : V { }
class List<T>
{
    public void Add<U>(List<U> items) where U : T {/*...*/}
}

`default`约束

参考文档: dotnet/csharplang/proposals/csharp-9.0/unconstrained-type-parameter-annotations

default约束是用于在重写/实现方法时消除nullable泛型重载的歧义。以下以代码演示其功能。

关于`?`标注

C# 8.0中，?仅能用于显式约束了值类型或引用类型的类型参数；在C# 9.0中，?可以用于任意类型参数，无论是否存在约束。
但要注意，?标注仅能用于设置了#nullable enable的代码上下文中。

若是类型参数T是个引用类型，T?表示该引用类型的可NULL实例。

1
2

var s1 = new string[0].FirstOrDefault();  // string? s1
var s2 = new string?[0].FirstOrDefault(); // string? s2

若是类型参数T是个值类型，T?表示该值类型的实例。

1
2

var i1 = new int[0].FirstOrDefault();  // int i1
var i2 = new int?[0].FirstOrDefault(); // int? i2

若是类型参数T是其他标注过的类型U?，T?依然表示标注过的类型U?，而不是U??。

1
2

var u1 = new U[0].FirstOrDefault();  // U? u1
var u2 = new U?[0].FirstOrDefault(); // U? u2

若是类型参数T是其他类型U，T?表示标注过的类型U?，即使在#nullable disable上下文中。

1
2

#nullable disable
var u3 = new U[0].FirstOrDefault();  // U? u3

实际上T?仅是个标注，并非一定是在构造新类型。
FirstOrDefault方法的声明是public static TSource? FirstOrDefault<TSource>(this IEnumerable<TSource> source);，返回值部分只是声明可能为NULL，并不是将返回值变成真正的可空类型TSource?。
对于值类型TSource(如int)，TSource?和TSource在IL中都是int，方法泛型返回值不能为int标注?(int?实际是Nullable<int>，是个新结构)。
对于返回值，T?等同于[MaybeNull] T，对于参数值，T?等同于[AllowNull] T。当重写方法或实现接口时该等同性非常重要。
以下代码演示了该等同性。

public abstract class A
{
    // 以特性方式声明抽象方法
    // 没有声明`class`/`struct`约束，编译器认为存在歧义，会添加`where T : default`约束

    // 实际等同于public abstract T? F1<T>(); (也会默认添加where T : default约束)
    [return: MaybeNull] public abstract T F1<T>();
    // 实际等同于public abstract void F2<T>(T? t)
    public abstract void F2<T>([AllowNull] T t);
}

public class B : A
{
    // 重写时必须显式声明where T : default约束
    public override T? F1<T>() where T : default { return defalut(T); } // matches A.F1<T>()
    public override void F2<T>(T? t) where T : default {  }             // matches A.F2<T>()
}

使用T?或注解形式的可为NULL声明且不存在class/struct约束时，编译器认为存在歧义，会默认添加where T : default约束，表示没有约束class/struct。
方法重写/实现接口时，必须声明where T : default约束，用来表示重写/实现的是不约束class/struct的方法。\

关于歧义

参考如下代码，除泛型约束外，两个方法是一致的形式，但方法签名不包含泛型约束信息。理论上，两个方法不应同时存在。

class C
{
    public virtual void F<T>(T? t) where T : struct { }
    public virtual void F<T>(T? t) where T : class { }
}

实际上，以上代码是合法的，两个方法是不同的签名。

C#8.0引入可为NULL引用类型支持，T?的意义取决于T是值类型或是引用类型。

泛型约束	`T?`的含义	真实参数类型
`where T : struct`	可为NULL值类型	`Nullable<T>`
`where T : class`	可为NULL引用类型	`T`(带可为NULL元数据)

以上代码在编译器视角中的实际形式如下。

using System.Diagnostics.CodeAnalysis;

class C
{
    public virtual void F<T>(Nullable<T> t) where T : struct { }
    public virtual void F<T>([AllowNull] T t) where T : class { }
}

两个方法的参数在编译器视角中是不同的类型，函数签名不同，因此可以同时存在。
但是对常规写法而言，用户读到的代码是一样的，因此便出现了歧义。

消除歧义

显式class/struct约束的代码，重写/实现时可以通过显式约束消除歧义。

class A1
{
    public virtual void F1<T>(T? t) where T : struct { }
    public virtual void F1<T>(T? t) where T : class { }
}

class B1 : A1
{
    public override void F1<T>(T? t) /*where T : struct*/ { }
    public override void F1<T>(T? t) where T : class { }
}

注: 显式struct约束的方法参数实际是Nullable<T>，相对于参数为T的方法，这是个约束更强(更具体)的版本，在编译器解析时具备更高的优先级。
因此重写方法时的where T : struct约束可以省去，但非常不建议这样做。

而当存在有约束和无约束版本的方法时，可以使用default约束来消除歧义。

class A2
{
    public virtual void F2<T>(T? t) where T : struct { }
    public virtual void F2<T>(T? t) { }
}

class B2 : A2
{
    public override void F2<T>(T? t) /*where T : struct*/ { }
    public override void F2<T>(T? t) where T : default { }
}

where T : default声明此处重写的是无class/struct约束的版本。

`unmanaged`约束

该约束可用于期望以直接操作内存块的方式读写类型实例的代码，如下所示。

unsafe public static byte[] ToByteArray<T>(this T argument) where T : unmanaged
{
    var size = sizeof(T);
    var result = new Byte[size];
    Byte* p = (byte*)&argument;
    for (var i = 0; i < size; i++)
        result[i] = *p++;
    return result;
}

由于对未知的类型T调用sizeof操作符，因此代码必须声明为不安全上下文(unsafe context)；若没有将类型参数T约束为unmanaged，sizeof操作符不可用。

委托约束

C#语言规范中未提供类似where T : delegate形式的约束，但可以用类型约束来实现类似的功能。
可以将T约束为System.Delegate/System.MulticastDelegate的子类，就可以在满足类型安全的前提下对委托进行操作。
代码演示如下所示。

// 操作委托的扩展方法
// 合并相同相同类型的委托
public static T? TypeSafeCombine<T>(this T source, T target) where T : Delegate
    => Delegate.Combine(source, target) as T;

// 定义两个相同类型的委托
Action first = () => Console.WriteLine("this");
Action second = () => Console.WriteLine("that");
// 合并&调用
var combined = first.TypeSafeCombine(second);   // √
combined!();

// 定义一个不同类型的委托
Func<bool> test = () => true;
// 如下的调用是错误的
var badCombined = first.TypeSafeCombine(test);  // ×

枚举约束

与委托调用类似，C#语言规范中并未直接提供纯粹的where T : enum约束(unmanaged约束允许传入枚举，但不是只允许枚举)，但可以用类型约束来实现类似功能。
可以将T约束为System.Enum的子类，就可以约束为仅允许枚举传入。
代码示例如下所示。

// 操作枚举的扩展方法
// 将给定枚举的值和名称构造成字典对象
public static Dictionary<int, string> EnumNamedValues<T>() where T : Enum
{
    var result = new Dictionary<int, string>();
    var values = Enum.GetValues(typeof(T));

    foreach (int item in values)
    {
        result.Add(item, Enum.GetName(typeof(T), item)!);
    }
    return result;
}
// 定义枚举
enum SomeValue {A, B, C, D}
// 调用扩展方法并初始化字典
var dict = EnumNamedValues<SomeValue>();

类型参数继承/实现声明的类/接口(F-Bound)

本质是F-Bound，此处仅简要介绍官方文档对该约束的介绍及演示(样例中涉及到对C#支持接口静态成员的语言功能)，请参考下文(F-Bound)对该技巧的详细介绍。

// T必须实现接口本身
interface IAdditionSubtraction<T> where T : IAdditionSubtraction<T>
{
    // C#接口支持声明静态成员
    static abstract T operator +(T left, T right);
    static abstract T operator -(T left, T right);
}

`allows ref struct`约束

该约束是C#13.0新增的语言功能。

allows ref struct实际上是反约束，允许指定的类型参数可以是ref struct类型，因此该类型实例必须遵守如下规则：

不能被装箱
必须遵守引用安全规则(ref safety rules)
不能在禁止使用ref struct的地方使用该类型，例如static字段
实例可以使用scoped修饰符进行标记

F-Bound

F-Bound是一种泛型编程技巧，通常用于面向对象编程中，帮助在继承层次结构中实现类型自参的自引用。简单来说，是指通过继承某个类型的泛型类，子类可以返回类型自己。这个技巧在做流式接口设计、构建DSL或者处理复杂类型时非常有用。

F-Bound通常用于实现以下模式：基类定义了一个泛型方法，该方法返回该类（或者子类）的类型。而子类继承基类时，能够实现这个方法并返回自己的类型。

以下代码演示基本应用。

using System;

// 基类 Shape，使用 F-Bound 技巧
public abstract class Shape<T> where T : Shape<T>
{
    // 一个设置颜色的方法，返回当前类型（T）本身
    public T SetColor(string color)
    {
        Console.WriteLine($"Setting color to {color}");
        return (T)this;  // 返回当前类型本身
    }
    // 计算形状的面积（可以在子类中实现具体的面积计算）
    public abstract double GetArea();
}

// Circle 类，继承自 Shape<T>，并指定自己为 T
public class Circle : Shape<Circle>
{
    public double Radius { get; set; }
    public Circle(double radius)
    {
        Radius = radius;
    }
    public override double GetArea()
    {
        return Math.PI * Radius * Radius;
    }
    // 可以链式调用 SetColor 方法
    public Circle SetRadius(double radius)
    {
        Radius = radius;
        return this;
    }
}

// Rectangle 类，继承自 Shape<T>，并指定自己为 T
public class Rectangle : Shape<Rectangle>
{
    public double Width { get; set; }
    public double Height { get; set; }
    public Rectangle(double width, double height)
    {
        Width = width;
        Height = height;
    }
    public override double GetArea()
    {
        return Width * Height;
    }
    // 可以链式调用 SetColor 方法
    public Rectangle SetDimensions(double width, double height)
    {
        Width = width;
        Height = height;
        return this;
    }
}

// 测试 F-Bound
class Program
{
    static void Main(string[] args)
    {
        // 创建一个 Circle 对象，设置颜色和半径
        Circle circle = new Circle(5);
        circle.SetColor("Red")
              .SetRadius(10);
        Console.WriteLine($"Circle Area: {circle.GetArea()}");

        // 创建一个 Rectangle 对象，设置颜色和尺寸
        Rectangle rectangle = new Rectangle(4, 5);
        rectangle.SetColor("Blue")
                 .SetDimensions(6, 7);
        Console.WriteLine($"Rectangle Area: {rectangle.GetArea()}");
    }
}

可变性

可变性(variance)包含协变(covariance)、逆变(contravariance)和不变(invariance)。
语言层面的可变性支持是类型系统支持多态的关键部分，有的是由严格的语法支持，有的语言通过子类型兼容性简介体现。

简单来讲，协变(covariance)是指子类型可以赋值给父类型，常用于返回值(输出)场景；逆变(contravariance)是指父类型可以赋值给子类型，常用于参数(输入)场景；不变(invariance)是指完全相同的类型才能赋值，最安全也最严格。

可变性的核心概念(类型转换中派生类与基类之间的方向)在非泛型场景中也存在，但一般是隐式的，或称为“类型兼容性”问题。有些“类型兼容性”问题(例如数组协变)依赖编译器推断，但在运行时检查，可能抛出异常。常规场景中，参数逆变，返回值协变，便已是足够完善可靠的规则。

语言	协变(covariant)	逆变(contravariant)	说明
C#	✅ `out`	✅ `in`	泛型接口/委托支持，数组协变（但运行时检查）
Java	✅ `? extends`	✅ `? super`	使用通配符在泛型中表达变体，没有关键字（只能在使用处）
Scala	✅ `+T`	✅ `-T`	在泛型定义中支持变体标注，极其灵活
Python	✅（Typing 协变）	✅（Typing 逆变）	使用 `typing.Generic` + `covariant=True` 表达
Kotlin	✅ `out T`	✅ `in T`	类似 C#，在泛型类型定义中支持关键字
Swift	✅ 协变支持	✅（使用 protocol）	支持返回值协变、协议泛型逆变较间接
TypeScript	✅ 自动推导	✅ 自动推导	没有变体关键字，但函数/接口参数/返回值类型由结构类型系统自动推导
Rust	⚠️ 不支持协变/逆变关键字	⚠️ 不支持显式变体	有复杂的生命周期变体（‘a: ‘b）机制，不针对泛型类型参数

语言	泛型定义处变体	使用处变体	自动推导	安全检查	使用推荐度
C#	✅ `in`/`out`	✅ 委托	❌	✅ 编译时	✅✅✅
Java	❌	✅ `? extends` / `? super`	❌	✅ 编译时	✅✅
Scala	✅ `+T` / `-T`	✅	✅	✅	✅✅✅✅
Kotlin	✅ `out T` / `in T`	✅	✅	✅	✅✅✅
Swift	❌	部分支持	❌	✅	✅✅
TypeScript	❌	✅	✅✅✅	✅（结构化）	✅✅✅
Python	✅ (Typing)	✅	❌	✅（类型检查器）	✅✅
Rust	❌ 泛型不支持	❌	❌	✅（生命周期）	✅（不同维度）

上表整理自ChatGPT,其中Kotlin/Swift/TypeScript/Rust的相关内容尚未审慎求证。

C#

官方文档:\

Covariance and contravariance in generics

Covariance and Contravariance (C#) - Overview

Variance in Generic Interfaces (C#)

Creating Variant Generic Interfaces (C#)

Using Variance in Interfaces for Generic Collections (C#)

Variance in Delegates (C#)

Using Variance in Delegates (C#)

Using Variance for Func and Action Generic Delegates (C#)

泛型接口/委托中的可变性

泛型类、泛型方法中不能独立使用可变性修饰符in/out

// 定义泛型接口(实际是标准库中的类型，此处用以演示)
// 比较器接口(逆变)
public interface IEqualityComparer<in T>
{
    bool Equals(T? x, T? y);
    int GetHashCode([DisallowNull] T obj);
}
// 只读集合接口(协变)
public interface IReadOnlyList<out T> : IEnumerable<T>, IEnumerable, IReadOnlyCollection<T>
{
    T this[int index] { get; }
}

// 简单的继承关系
class Base { }
class Derived : Base { }

// 实现基类的比较器
class BaseComparer : IEqualityComparer<Base>
{
    public int GetHashCode(Base baseInstance)
    {
        return baseInstance.GetHashCode();
    }

    public bool Equals(Base? x, Base? y)
    {
        return x == y;
    }
}

// 基类的比较器可以作为派生类的比较器使用，此处体现了逆变
IEqualityComparer<BaseClass> baseComparer = new BaseComparer();
IEqualityComparer<DerivedClass> childComparer = baseComparer;

// 子类的集合可以作为基类的集合的使用，体现了协变
IReadOnlyList<Derived> childList = [];
IReadOnlyList<Base> baseList = childList;

// 泛型委托定义，参数逆变，返回值协变
public delegate TResult Func<in T, out TResult>(T arg);

// 两个委托实例
// 委托1：接受派生类，返回基类
Func<Derived, Base> func1 = (Derived d) =>
{
    Console.WriteLine(d);
    return new Base();
};
// 委托2：接受基类，返回派生类
Func<Base, Derived> func2 = (Base b) =>
{
    Console.WriteLine(b);
    return new Derived();
};

// 参数逆变：委托1期望接受派生类，实际可以接受基类
// 返回值协变：委托1期望返回基类，实际可以返回派生类
// 因此以下赋值是有效的(类型兼容)，委托2的实例可以作为委托1的实例调用
func1 += func2;

非泛型场景中的可变性

数组协变(强烈不推荐使用)

// 构造字符串数组实例，可以赋值给对象数组
object[] array = new string[] { "a", "b", "c" };
// 一般的读取不会有类型安全问题
var value = array[0];
// 赋值语句可以通过编译，但会在运行时抛出异常
array[0] = 1;

类型不安全。
该功能是编译器隐式支持的功能，但在运行时检查安全性。
协变的数组变量不存在严格的写保护，极有可能出现不经意的赋值操作，生产环境中应当避免使用。

方法重写返回值类

class A
{
    // 基类型中定义虚方法，返回值是基类型A
    public virtual A CreateInstance() { return new A(); }
}

class B : A
{
    // 派生类中重写方法，返回值类型是派生类型B，返回值协变
    public override B CreateInstance() { return new B(); }
}

类型安全。
该功能是编译器隐式支持的功能。
虚方法在子类中重写时，参数必须保持一致，但返回值可以是更具体的类型(返回值是协变的)，两个方法依然是“类型兼容”的。

非泛型委托的协变和逆变

// 定义基类型Animal及派生类型Dog
class Animal { }
class Dog : Animal { }

// 定义委托类型
delegate Animal Creator();
delegate void Handler(Dog dog);

// 定义普通方法
static Dog CreateDog() { return new Dog(); }
static void FeedAnimal(Animal animal) { }

// 方法可以构造为委托实例
Creator creator = CreateDog;    // 返回值协变
Handler handler = FeedAnimal;   // 参数逆变

类型安全。
该功能是编译器隐式支持的功能。
委托Creator期望生产Animal实例，实际上得到Dog实例，Dog作为Animal使用是类型安全的，因此Dog生产者作为Animal生产者也是类型安全的。这体现的是协变。
委托Handler期望消费Dog实例，因此调用Handler时给出的必定是Dog(或Dog派生类)实例，现在handler实际上是个消费Animal的实例，Dog作为Animal使用是类型安全的，消费Animal的方法消费Dog也是类型安全的，因此Animal消费者作为Dog消费者也是类型安全的。这体现的是逆变。
委托可以视为类型安全的函数类型，函数类型也可以视为构造类型(由参数类型+返回类型构造),在这个视角看待类型兼容也许有不一样的发现。可参考本站文章CTFP(category theory for programmer/面向程序员的范畴论)中协变和逆变的相关内容。

高阶泛型

Higher Kind

Higher Rank

参考链接

Generic programming

Parametric polymorphism

本文内容经过较长时间整理、

Scala Style

Thu, 16 Jul 2020 00:00:00 +0800

Scala Style

参照官方文档推荐的Scala代码风格SCALA STYLE GUIDE

缩进和换行

该部分参考INDENTATION

每个缩进级别都是2个空格

尽量保证每行不要超过80字符，若有表达式超出了，尽量考虑换行

// 缩进是2个空格
object Foo {
  def bar(): Unit = {
    val x = 10
    //...
  }
}

// ---

// 超长表达式的换行
val result = 1 + 2 + 3 + 4 + 5 + 6 +
  7 + 8 + 9 + 10 + 11 + 12 + 13 + 14 +
  15 + 16 + 17 + 18 + 19 + 20

// 超多参数的函数调用，变量名超长时要注意方法在新一行开始调用
val myLongFieldNameWithNoRealPoint =
  foo(
    someVeryLongFieldName,
    andAnotherVeryLongFieldName,
    "this is a string",
    3.1415)

命名约定

该部分内容参考NAMING CONVENTIONS

绝大多数情况下，Scala采用小驼峰风格lowerCamelCase，一些缩写术语也作为普通单词对待xHtml/maxId，由于下划线在Scala语法中有特殊意义，因此非常不推荐使用（若要强行使用、编译器也不会主动拒绝此类代码）

类、特质

类和特质的命名应当遵循大驼峰风格，跟Java中对于类的命名约定是一致的

有时类或特质以及它们的成员是用于描述格式、文档或者某些协议，此时为了保持与输出一模一样，可以不遵循对类名和成员的命名约定。但应注意只能在这种特定用途使用，不能影响其余代码

对象

对象一般也遵循大驼峰命名风格，但是当之功能上模仿包或者函数的时候，可以不遵循这一约定

// 功能类似一个名为`ast`的包
object ast {
  sealed trait Expr

  case class Plus(e1: Expr, e2: Expr) extends Expr
  ...
}

// 功能类似一个名为`inc`的函数
object inc {
  def apply(x: Int): Int = x + 1
}

包

对包的命名应当遵循Java的命名约定，例如com.foo.bar

有时会出现必须用_root_指定包的全名的情况。但应注意不要过度使用_root_，以相对包路径方式来引用嵌套包是很推荐的做法，此外这十分有助于简化import语句

方法

Scala中，对于普通文本/字母名称的方法应当采用小驼峰风格

Accessors/Mutators 属性访问器、修改器

其功能可以直接对应成Java中常用的getter/setter，但是命名风格与Java完全不一致，Scala中采用一下约定

对于属性的访问器/Accessors，该方法的名称与属性名称保持完全一致

某些情况下，对于Boolean类型的访问器，允许在前面加上is（例如isEmpty），这种情况下也要保证没有相应的修改器才行。（Lift框架中，对此种情况的约定是在属性名后加_?，这是非标做法，注意不要滥用该做法）

对于修改器/Mutators，其方法名应当是在属性名后加_=。遵循该约定后，调用点对属性的赋值将映射为调用该修改器方法（这不再仅是个约定，而变成了语言的约束）

class Foo {
  def bar = ...
  def bar_=(bar: Bar) {
    ...
  }
  def isBaz = ...
}

val foo = new Foo
foo.bar             // accessor
foo.bar = bar2      // mutator
foo.isBaz           // boolean property

由于Java没有对于属性及其绑定的一等支持，因此有了getter/setter范式的存在。在Scala中，有专门的库用于做此类支持

1
2
3

class Company {
  val string: Property[String] = Property("Initial Value") // 一个不变的属性对象引用，但属性对象保存的值是可以修改的
}

无参方法/函数的括号

定义和调用无参方法/函数时，应当注意并考虑清楚是否要带括号

1
2

def foo1() = ...
def foo2 = ...

以上两个方法在Scala中都是合法的，两者也是不同的。其中foo2只能无括号方式调用、但foo1可以带括号调用。

实际行为类似访问器的方法、而且方法调用无任何副作用，那么声明时不应当带括号。若有副作用，那么就应当带上括号。调用时也应当遵循此约定，若是要调用含副作用的方法，注意带上其括号

符号方法名

尽量避免！

Scala语言库中符号用得很多，但实际编程中对于符号的使用还是应当慎重考虑，尤其是这一符号没有其标准意义时。两个合理的使用场景是：DSL中(actor ! msg)；数学操作符（a + b c :: d）。在标准的API设计领域，严格限制符号方法名只能使用在纯函数式操作中。可以定义>>=来进行单子的bind操作，但是不允许定义<<方法向输出流写东西。因为前者是有完备数学定义的，而且没有任何副作用，但后者既没有标准定义也不是无副作用的操作。

一般而言，能以符号命名的方法应当是广为人知或者能很好地自描述的。一旦需要解释这个方法到底在做什么，那么该方法就不适合用符号名称了。

常量、值、变量和方法

常量命名应采用大驼峰风格，例如scala.math.Pi；一般的值、变量和方法应采用小驼峰命名风格

类型参数（泛型）

简单的类型参数一般用一个大写字母即可，一般从A开始

1
2
3

class List[A] {
  def map[B](f: A => B): List[B] = ...
}

若是类型参数有特定意义，那么可以用具备描述性的单词，该单词遵循类型的命名规则（注意不是全大写）；当然，若是的类型参数的作用域足够小，直接用单个字母依然没有问题

// 可以用单词
class Map[Key, Value] {
  def get(key: Key): Value
  def put(key: Key, value: Value): Unit
}

// 也可以用字母
class Map[K, V] {
  def get(key: K): V
  def put(key: K, value: V): Unit
}

HKT

理论上讲，高阶类型参数跟一般类型参数没什么不同（当然高阶kind至少是* => *而不是简单的*）。一般而言，更倾向于使用更具描述性的单词，而不是一个简单的字母，例如class HigherOrderMap[Key[_], Value[_]] { ... }。对于一些基础概念，可以用简单的字母，例如F[_]来表述函子、M[_]表述单子。

注解

Scala中注解一般采用小驼峰

特别说明

由于Scala本质上是函数式编程语言，因此def add(a: Int, b: Int) = a + b这种名称短小、方法体简单的函数定义很常见。这种行为在Java中是个很不好的做法，但是在Scala中是很推荐的。

类型

该部分内容参考TYPES

类型推断

在保证代码清晰的前提下，尽可能地用上类型推断的功能。在向外开放API的地方，注意显式给出类型信息。

对于私有字段或本地变量，几乎完全不用显式给出类型，因为它们的类型我们一般能直接从值上看出来，对于那些不那么明显的、或者比较复杂的，还是应该显式给出类型。对于所有的公共成员，必须明确给出类型信息。

特别地，Scala编译器对于函数值/λ表达式的类型推断做了特殊处理，对于需要传入函数的高阶函数调用，可以不必声明该表达式参数的类型。考虑ints.map(i => i * 2)，编译器可以直接推断出λ表达式的参数i的类型。

类型注解

类型注解该以如下方式写value: Type，例如i: Int、d: Double甚至l: ::

Type ascription / 类型归属？

类型归属的语法跟类型注解是一致的，所以很容易搞混，例如Nil: List[String] None: Option[String] "Str12": AnyRef Set(values: _*)。类型归属是在向编译器声明我们期望该值的类型是什么，一般在做上转型操作，前三者例子便是如此；但Scala中更常见的可能是最后一例，当调用一个可变参数的方法时、期望将序列展开，因此用到_*（否则会变成可变参数列表仅接收到一个参数，该参数是个序列）

函数

函数的类型遵循(argType1, argType2, ...) => retType的写法。特别地，对于元数为1的函数，可以省去参数的括号，写作argType => retType

结构类型

若是结构类型的总长度小于50字符，那么应该写在一行里，否则就应写作多行，并且为之分配一个类型别名。

// 简单结构类型
def foo(a: { val bar: String }) = ...

// 复杂结构类型
private type FooParam = {
  val baz: List[String => String]
  def bar(a: Int, b: Int): String
}

def foo(a: FooParam) = ...

当把简单结构类型写在一行的时候，多个成员之间应该用一个分号和空格隔开，成员跟花括号之间也应有空格

结构类型是在运行时用反射实现的，因此性能较差。开发时还是应尽可能选择常规类型，除非结构类型能带来明显的益处

嵌套代码块

NESTED BLOCKS

代码块

左花括号必须跟它所归属定义的声明放在同一行

括号

当某表达式跨越多行且需要小括号包裹时，左右两小括号与其包裹的内容之间应当没有空格、并且与内容保持同一行；

1
2

(this + is a very ++ long *
  expression)

小括号也可用于禁用分号推断，因此允许更喜欢将操作符写在开头的开发者写出如下代码

(  someCondition
|| someOtherCondition
|| thirdCondition
)

声明

DECLARATIONS

类

类、对象、特质的构造器应当尽可能放在一整行里，当这一行过长（比如超出100字符）的时候，那么需要将该行拆成多行，每个构造器参数及其跟随的逗号占一行，如下所示

// 单行形式
class Person(name: String, age: Int) {
  …
}

// 多行形式
class Person(
  name: String,
  age: Int,
  birthdate: Date,
  astrologicalSign: String,
  shoeSize: Int,
  favoriteColor: java.awt.Color,
) {
  def firstMethod: Foo = …
}

若是该类、对象、特质扩展了其他成员，采用同样的规则。尽可能放在一行里，若是单行超出100字符，那就拆成如下的多行形式

class Person(
  name: String,
  age: Int,
  birthdate: Date,
  astrologicalSign: String,
  shoeSize: Int,
  favoriteColor: java.awt.Color,
) extends Entity
  with Logging
  with Identifiable
  with Serializable {

  def firstMethod: Foo = …
}

类中各元素的顺序

类、对象、特质中的所有成员之间一般都应当用一个空行隔开。对于val和var，如果定义足够简单（比如单行少于20字符）并且没有Scala Doc，那么多个val或var之间可以不加空行。

一般而言，字段定义应当在方法之前，但当字段求值是多行表达式的时候，此时字段实际上有点方法的味道了（例如在List上计算其长度）。这样的字段可以在文件靠后的位置，注意，仅限val和lazy val使用这一后放规则。注意千万不能把var在类里面放得遍地都是

方法

方法应当以def foo(bar: Baz): Bin = expr形式进行声明，若是方法参数有默认值，应当在等号两侧加空格。注意，应当对于所有公有成员声明返回类型，既能显式描述方法返回类型，也能避免编译器推断的返回类型在实现修改后发生变化，从而导致二进制不兼容。本地方法或私有方法可以不显式给出返回类型

过程式语法

编程实践中尽量不要用过程式语法

// don't do this
def printBar(bar: Baz) {
  println(bar)
}

// write this instead
def printBar(bar: Bar): Unit = {
  println(bar)
}

方法修饰符

对方法的修饰符应当按以下顺序。注解、每个注解单独一行；重写标识符override；访问控制修饰符protected、private；隐式关键字implicit；final关键字；def关键字

方法体

若是方法体只是一行简单表达式，那么不必用花括号包裹起来，若该表达式比较短（比如少于30字符），那么跟方法定义直接写在一行即可；该表达式比较长的话，那么就新起一行。具体选择哪种比较主观，总体思想是使代码可读性更好，若是方法声明很长但表达式很短，那也应当写在新一行里，避免使声明行过长。

对于仅有match表达式的方法，xx match {应与方法声明写在同一行。

方法体是多行表达式的时候，应注意必须用花括号。

多参数列表

应当仅在有着充分理由的时候使用该语言功能，一般而言，有以下三方面原因驱使编写该风格代码：Fluent API设计、隐式参数、为了更好的类型推断

// 自定义流程控制API
def unless(exp: Boolean)(code: => Unit): Unit = if (!exp) code

unless(x < 5) {
  println("x was not less than five")
}

// 对于多参数列表，给出第一个参数后，其余参数可以用编译器类型推断来简化编写

// scala中，一般这样定义
def fold[U](unit: U)(op: (U, A) => U): U
// 这样调用
List("").fold(0)(_ + _.length)

// 若是这样定义
def fold[U](unit: U, op: (U, A) => U): U
// 只能这样声明具体类型的调用
List("").foldLeft[Int](0, _ + _.length)
// 下面这种调用是不对的
List("").fold(0, (i: Int, s: String) => i + s.length)

对于复杂DSL或者类型名称超长的类型，可能很难在一行中完整声明整个函数签名，这种情况可以每个参数列表占一行，左括号对齐

高阶函数

在Scala中，只要在声明函数的时候稍微留心，那么调用高阶函数的时候可以有一些语法上的简化。考虑fold函数，SML中它的签名fun fold (f: ('b * 'a) -> 'b) (init: 'b) (ls: 'a list)，在Scala中，一般是相反的参数顺序def fold[A, B](ls: List[A])(init: B)(f: (B, A) => B): B = ...。把函数参数放在最后一个，那么调用该函数的时候，可以用上函数简化语法fold(List(1,2,3,4))(0)(_+_)

字段

字段遵循的声明规则跟方法大约一致。此外，对于lazy的字段，val必须紧跟lazy关键字

函数值

Scala允许多种语法声明函数值，例如，以下几种方式都是正确的

val f1 = ((a: Int, b: Int) => a + b)
val f2 = (a: Int, b: Int) => a + b
val f3 = (_: Int) + (_: Int)
val f4: (Int, Int) => Int = (_ + _)

其中，第一种和第四种方式是建议写法，第二种相对也还行，但是当函数体多行的时候容易出现问题；第三种是最简洁的，但是可能比较难以理解，尤其是一眼看上去可能看不懂，得想一下才能懂什么意思。

函数值中，在小括号和它们包裹代码之间不应当有空格，但花括号与其代码见应用空格。

大部分函数可能不像上例给出的那样简要，它们可能都是有多行表达式。这种情况下，就将函数切分到多行去，这种情况下必须用第一种风格

val f1 = { (a: Int, b: Int) =>
  val sum = a + b
  sum
}

此外，函数值的声明和调用都应尽可能发挥编译器类型推断的功能。

控制结构

CONTROL STRUCTURES

所有的控制结构关键词if/for/while之后都必须紧跟一个空格

花括号

当控制结构表达的是一个纯函数式操作并且各个分支都只是单行表达式时应当省略花括号

if表达式：若是存在else分支，则应当省略花括号；否则必须用花括号包裹起来，哪怕只有单行表达式
while：必须带上花括号（因为它永远不可能描述一个纯函数式操作）
for：若是有yield语句，那么可以省略花括号；否则必须用花括号包裹循环体，哪怕仅有一行表达式
case: 省略花括号

val news = if (foo)
  goodNews()
else
  badNews()

if (foo) {
  println("foo was true")
}

news match {
  case "good" => println("Good news!")
  case "bad" => println("Bad news!")
}

`for`-Comprehensions

在for语句中可以写多个生成器（即多个<-）对于存在yield语句的for表达式，当有多个生成器的时候，要用花括号包裹且每个生成器占一行；仅有一个生成器的时候，用小括号包裹，如下

// right
for (i <- 0 to 10) yield i

// wrong!
for (x <- board.rows; y <- board.files)
  yield (x, y)

// right!
for {
  x <- board.rows
  y <- board.files
} yield (x, y)

存在特例，对于那些没有yield的for表达式，这种情况属于普通的循环而不是函数式操作，此时使用小括号包裹一个或多个生成器

// wrong!
for {
  x <- board.rows
  y <- board.files
} {
  printf("(%d, %d)", x, y)
}

// right!
for (x <- board.rows; y <- board.files) {
  printf("(%d, %d)", x, y)
}

for-comprehensions可能会常倾向于链接map、flatMap、filter等调用，但是会导致代码可读性很差，因此这种情况要尽可能用增强的for表达式

细碎的条件判断

有些需要三元操作符?/:的场景，scala中无这样的操作符，但是可以直接用简单的if/else表达式来表述，例如val res = if (foo) bar else baz。要注意这种风格不要在命令式运用if/else时使用

方法调用

METHOD INVOCATION

简要来讲，Scala中的方法调用遵循Java风格的约定。在调用对象、点、方法名之间没有空格，方法名和参数列表之间没有空格，参数之间应当以逗号和一个空格隔开。

Scala 2.8开始支持了命名参数，进行方法调用时，命名参数整体应当看作一个普通参数（即逗号加一个空格分隔），命名参数自身等号两侧应当各有一个空格

foo(42, bar)
target.foo(42, bar)
target.foo()

foo(x = 6, y = 7)

0元函数/无参函数

Scala允许省略0元函数调用时的括号。当要调用的方法没有任何副作用的时候才能用这种语法，否则必须带上括号。

xx.toString()     // √
xx.toString       // √

println()         // √
println           // x

Postfix Notation/后缀写法

此外，对于无参数函数，Scala也允许采用后缀写法，但是要尽可能避免，这里只是给出了有这种写法，但是非常不建议使用。仅限在某些DSL中才允许用这种写法。

1
2

names.toList    
names toList    // x

1元函数/单个参数 - 中缀写法

对于这类函数，Scala允许一种完全无需任何符号的语法，即中缀写法。通常情况下，应当注意避免这种语法，但当方法名是个符号参数部分是个函数的时候可以用，当然也必须保证是在纯函数的环境中用。

1
2
3

names.mkString(",")     // √
names mkString ","      // 有时会见到这种写法，但这种写法存在争议，要避免
javaList add item       // x

符号方法、操作符

这种方法/函数必须要以中缀风格来进行调用。

"daniel" + " " + "spiewak"    // √
a + b                         // √

"daniel"+" "+"spiewak"        // x
a+b                           // x
a.+(b)                        // x

绝大多数情况下，遵循Java和Haskell中的约定。在某些灰色地带中，对那些方法名短小、实际效果类似操作符的函数，尤其是当它满足了交换律的时候，例如max，x max y这种写法也是相当常见的。

符号方法可能接受多个参数，这种情况下要用中缀语法来调用，foo ** (bar, baz)。这种方法其实相当少了，在设计API的时候应注意，尽可能避免设计出这样的API。Scala的集合API设计中存在/:和:\，尽量不要使用它们，转而使用更具意义的方法名foldLeft和foldRight。

高阶函数

对于那些接受一个函数为参数的方法，应尽量使用的中缀语法。但是用中缀语法的时候不要带着多余的符号了

1
2
3

names.map { _.toUpperCase }                           // x
names.map { _.toUpperCase }.filter { _.length > 5 }   // √
names map { _.toUpperCase } filter { _.length > 5 }   // √

文件

FILES

一般来讲，文件中应当只包含逻辑上的单个组件。所谓“逻辑上”的单个组件，指的是一个类型、特质或对象。当类或特质有其伴生对象时，要将伴生对象放在类或特质的同一文件中。文件名应当就是类、特质或对象的名称。此外，应当按照其包的结构放在相同目录结构中。

Scala放宽了对于文件名、目录结构的限制，但实际编程中还是应注意遵循Java风格的约定。

package com.novell.coolness

class Inbox { ... }

// companion object
object Inbox { ... }

多元素文件

有些很特殊的情况就是要违反以上约定。

一个很常见的例子便是对于封闭抽象类、封闭特质及其子类的实现（一般是对ADT相关功能的实现）。因为封闭类、特质从语言级别就约束了其子类必须与其在同一个源文件中。

sealed trait Option[+A]

case class Some[A](a: A) extends Option[A]

case object None extends Option[Nothing]

另一个常见场景是多个类从逻辑上很内聚，它们基于同样的一组前提或者概念，为方便维护便放在了同一个源文件中。这种情况确实存在，但应仔细斟酌是否放到一个源文件中

所有的多元素文件都必须以小驼峰给文件命名

例如option.scala、ast.scala

文档

SCALADOC

应当为所有的包、类、特质、方法及其他成员提供详细的文档。Scala文档遵循Java的文档风格，此外也提供了更丰富的功能用于简化文档的书写。

应当更关注文档的主旨和内容，而不是格式。文档以简短的概括开始，然后再给出更深入的细节描述。一下给出几种常见风格

// ---- Java doc 风格 ----

/**
 * Provides a service as described.
 *
 * This is further documentation of what we're documenting.
 * Here are more details about how it works and what it does.
 */
def member: Unit = ()

// ---- Scala doc 风格 （星号在第二列对齐） ----

/** Provides a service as described.
 *
 *  This is further documentation of what we're documenting.
 *  Here are more details about how it works and what it does.
 */
def member: Unit = ()

// ---- Scala doc 风格 （星号在第三列对齐） ----

/** Provides a service as described.
  *
  * This is further documentation of what we're documenting.
  * Here are more details about how it works and what it does.
  */
def member: Unit = ()

// ---- 某些特别简单的注释 ----

/** Does something very simple */
def simple: Unit = ()

SCALADOC FOR LIBRARY AUTHORS

Higher Kinded Type - 高阶类类型

Thu, 28 May 2020 00:00:00 +0800

Higher Kinded Type - 高阶类类型

Kind

维基百科：Kind (type theory)

“kind"中文翻译也是“类型”，这样就跟"type"有些混淆。下文仅将“type”翻译类型。

Kind是类型理论(Type Theory)中的定义。一个kind便是一个类型构造器的类型(the type of a type constructor)，或者说是高阶类型类型操作符的类型(the type of a higher-order type operator)。

Kind System本质上是简单类型Lambda演算(simply typed lambda calculus)的“上一层”。定义一个原始类型(primitive type)(记作*/$*$、称之为“type”)，它是任意数据类型(data type)的kind，不需要任何类型参数。

kind有个可能看上去有些莫名其妙的解释：“(数据)类型的类型”（type of a (data) type），但实际上它也有些元数指示的意思。从语法上讲，可以很自然地将多态类型视为类型构造器，因此非多态类型可以视为一个0元类型构造器/无参类型构造器，所有的无参类型构造器都是相同的、最简单的kind，便是*/$*$

高阶类型操作符在编程语言中并不常见，在大多数编程实践中，kind用于区分数据类型和用于实现参数化多态的构造器类型(types of constructors which are used to implement parametric polymorphism)。在类型系统使得用户能编码实现参数化多态的编程语言中(如C++ Haskell Scala)，或明或暗地有kind的概念存在。

Examples

*/$*$是所有数据类型的kind，读作"type”，也可看作0元类型构造器/无参类型构造器，在当前上下文中也称为恰当类型(proper type)，通常也包含函数式编程语言中的函数类型。例如Int/Bool/List<Int>/Map<String, List<Double>>的kind都是*
* -> */$* \rightarrow *$是一元类型构造器(unary type constructor)的kind。例List类型的kind便是* -> *，需要给出一个类型参数Int才能得到恰当类型List<Int>
* -> * -> */$* \rightarrow * \rightarrow *$是二元类型构造器(binary type constructor，curry方式实现)的kind。例如Tuple便是二元类型构造器；函数类型构造器->也属此类（注：对->应用的结果是函数类型，函数类型kind是*）
(* -> *) -> */$(* \rightarrow *) \rightarrow *$是从一元类型构造器到恰当类型的高阶类型操作符的kind

Values	Types	Kinds
`1`	`Int`	`*`
`[1,2,3]`	`List<Int>`	`*`
`(1, "")`	`Tuple<Int, String>`	`*`
`fun i -> i % 2 == 0`	`Int -> Bool`	`*`
-	`List`	`* -> *`
-	`Tuple`	`* -> * -> *`
-	`->`	`* -> * -> *`

从左向右提升抽象层次

Kind In Haskell

Haskell的Kind系统中，$K = * | K \rightarrow K$，它描述了两条规则：*/$*$是所有数据类型的kind；* -> */$* \rightarrow *$是一元类型构造器的kind，接受一个kind然后给出一个kind。

确实有值的类型才是算作具体类型，或者叫恰当类型。例如，4是Int类型的值、[1, 2, 3]是[Int]类型的值、fun i -> i % 2 == 0是Int -> Bool类型的值、fun x -> fun y -> x % y == 0是Int -> Int -> Bool类型的值。这些类型的kind都是*。

一个类型构造器接受一个或多个类型参数，当接受了足够的类型参数之后便产生了一个新类型(类型构造支持基于currying的偏应用)。例如，[]/List接受一个类型参数，这个类型参数指出了内部元素的类型，因此[Int]/[Bool]/[[Int]]都是对于[]的正确应用，[]的kind是* -> *，Int/Bool/[Int]的kind是*，将之应用到[]便得到[Int]/[Bool]/[[Int]]，这些结果类型的kind是*。同理，二元组类型构造器(,)的kind是* -> * -> *，三元组类型构造器(,,)的kind是* -> * -> * -> *

HKT in Programming

静态类型语言中，类型系统来保证值的使用安全性，kind系统是来保证类型的使用安全性。

主流编程语言中提供的一般是一阶参数化多态(first-order parametric polymorphism)，这一功能一般称为泛型(generic)。泛型能对类型进行抽象并进行静态检查，但无法对类型构造器进行抽象，进而无法保证这方面类型安全(不支持HKT的话也写不出来，因为编译器不接受这样的代码，只能舍弃抽象，从而导致代码重复)。

// ---------- Version 1 ----------
trait Iterable[T] {
    def filter(p: T => Boolean): Iterable[T]
    def remove(p: T => Boolean): Iterable[T] = filter(x => !p(x))
}

trait List[T] extends Iterable[T] {
    def filter(p: T => Boolean): List[T] = ???
    override def remove(p: T => Boolean): List[T] = filter(x => !p(x))
}
// ---------- Version 2 ----------
trait Iterable[T, Container[_]] {
    def filter(p: T => Boolean): Container[T]
    def remove(p: T => Boolean): Container[T] = filter(x => !p(x))
}

trait List[T] extends Iterable[T, List]

以上代码用Scala简单演示了引入HKT带来的收益，确实减少了不必要的代码重复，而对于类型安全的保证也不会有任何损失。下面是个稍复杂些的例子，用Haskell和Scala对函子进行定义和实现，从而对HKT进行演示。

-- Functor in Haskell
class Functor f where
    fmap :: (a -> b) -> f a -> f b

-- data Maybe a = Nothing | Just a
instance Functor Maybe where
    fmap _ Nothing = Nothing
    fmap f (Just x) = Just (f x)

-- data List a = Nil | Cons a (List a)
instance Functor List where
    fmap _ Nil = Nil
    fmap f (Cons x xs) = Cons (f x) (fmap f xs)

-- `(->)` is a type constructor. `(->) r a` => `r -> a`
-- here: `fmap :: (a -> b) -> (r -> a) -> (r -> b)`
instance Functor ((->) r) where
    fmap f g = f . g

// Functor in Scala
trait Functor[F[_]] {
    def fmap[A, B](f: A => B)(fa: F[A]): F[B]
}

object OptionFunctor extends Functor[Option] {
    def fmap[A, B](f: A => B)(a: Option[A]): Option[B] = {
        a match {
            case None => None
            case Some(x) => Some(f(x))
        }
    }
}

object ListFunctor extends Functor[List] {
    def fmap[A, B](f: A => B)(list: List[A]): List[B] = {
        list match {
            case Nil => Nil
            case head :: tail => f(head) :: fmap(f)(tail)
        }
    }
}

class FunctionFunctor[R] extends Functor[({type λ[A] = R => A})#λ] {
    def fmap[A, B](f: A => B)(g: R => A): R => B = {
        f compose g
    }
}

分析以上代码，定义函子Functor用到了参数f/F[_]，该参数是个类型构造器，其kind便是* -> *，于是函子Functor的kind便是(* -> *) -> *，这里便是kind的“高阶”所在。此外要注意函数类型构造(->)，对于其返回类型呈(协变)函子性，因此可以固定函数参数类型为r/R，然后可实现r -> ?/R => ?函子。Scala中需要显示指出类型构造器，Haskell可以通过对于参数的应用推断出这是个类型还是个类型构造器。

论文Generics of a Higher Kind解释了Scala对于HKT的设计及应用演示，论文中给出了一个更具实用意义的例子，通过对Iterable基础类库的设计和实现，演示了HKT存在的必要性（上文已简要演示）。此外也简要解释了Scala的“implicit”设计理念，该设计以另一种方式提供了Haskell的Type Class提供的特设多态(ad-hoc polymorphism)功能。此外，Scala的Kind System中，kind还附带着类型的上下界、可变性的约束信息，以此来确保程序的正确性。

F#尚不支持HKT，需要CLR改进才能支持这一功能，对功能的讨论在：Simulate higher-kinded polymorphism。Robert Kuzelj的Higher Kinded Types in F#系列博客演示了HKT存在的必要性以及在F#中如何对其进行模拟。

Higher Kinded Types in typescript博客介绍了在TypeScript中对HKT功能进行模拟。

Rust对HKT的似乎也开始支持，高阶类型 Higher Kinded Type对此进行了简单介绍，看评论似乎不是HKT完整支持。

1. 准备开发环境

Mon, 09 Mar 2020 00:00:00 +0800

准备开发环境

Windows
- JDK
- Scala SDK
- Spark
- IDEA
WSL / Linux
- VSCode Remote

在Windows系统配置开发及测试环境

Windows

JDK

安装

需要下载安装两个版本的JDK：
- JDK 1.7：用于适配公司平台打包程序使用，互联网环境做测试可以先不装。现在很难下到了，内网的话，咱们自己有。
- JDK 1.8：本地运行Spark Shell使用，Oracle现在贼了不少，需要Oracle账户才能下载，百度上有很多分享，搜一个就行
对于我们目前的开发和测试，请使用JDK1.8，先不要使用JDK11(虽然它是LTS)。（测试过JDK11+Scala，有的行为不一致，可能是Scala对高版本JDK的优化？？？）
配置JAVA_HOME环境变量

将JDK 1.8配置到JAVA_HOME作为全局使用

注意：Spark运行的时候是查找JAVA_HOME环境变量然后运行，不是从PATH中的java.exe启动

注意：如果将JDK安装在默认位置，如C:\Program Files\Java\jdk1.8.0_241\，由于路径中的空格问题，将会导致Windows上的Spark Shell启动失败，将JAVA_HOME环境变量修改成：C:\PROGRA~1\Java\jdk1.8.0_241\这种形式

配置PATH环境变量

这个步骤不是必须，但是建议做，环境变量配置完毕后，可以用java -version命令来验证安装

PS C:\Users\mxtao> java -version
java version "1.8.0_241"
Java(TM) SE Runtime Environment (build 1.8.0_241-b07)
Java HotSpot(TM) 64-Bit Server VM (build 25.241-b07, mixed mode)
PS C:\Users\mxtao>

Scala SDK

需要下载安装两个版本的Scala SDK：

Scala 2.10.7: 用于适配公司平台打包程序使用
Scala 2.11.12：面向测试环境开发程序使用

将两个Scala SDK的zip下载并解压到某处即可，如C:\Program Files\Scala\，不需要配置环境变量。安装完毕之后，可以进入安装目录尝试启动一下Scala REPL，可以在这个环境尝试一下Scala语言。

PS C:\Program Files\Scala\scala-2.11.12\bin> .\scala
Welcome to Scala 2.11.12 (Java HotSpot(TM) 64-Bit Server VM, Java 1.8.0_241).
Type in expressions for evaluation. Or try :help.

scala> :quit
PS C:\Program Files\Scala\scala-2.11.12\bin>

如果是互联网环境开发，Scala SDK的手动安装可以跳过，使用IDEA来下载Scala SDK，如下图所示。

Spark

下载安装Spark

建议从Downloads | Apache Spark找到最新稳定版进行下载，建议选择“Pre-build for Apache Hadoop”版本进行下载，这样避免配置Hadoop环境的麻烦。此处附上国内清华镜像的Spark 2.4.5 & Hadoop 2.7。将这个压缩包解压到某处即可，如C:\Software\Spark\

Spark目录下的examples是一些样例代码，包含Spark Core、Spark SQL及其它组件的使用样例，可以直接参考使用
配置WinUtils

若要使Hadoop在Windows上正常运行，需要做些别的事情。从此处cdarlint/winutils找到对应或者更高版本的winutils下载下来。此处附上该项目的完整ZIP。

我们前面下载的Spark附带的是Hadoop 2.7，因此我们选择了适配2.7.7版本的winutils，将所有文件放在C:\Software\Hadoop\bin中，此时winutils.exe完整路径为C:\Software\Hadoop\bin\winutils.exe

现在开始配置环境变量，新增名为HADOOP_HOME的环境变量，其值为C:\Software\Hadoop，然后在PATH环境变量中添加%HADOOP_HOME%\bin\

必须配置HADOOP_HOME环境变量

启动Spark Shell

进入上文Spark的安装目录，尝试启动Spark Shell检查安装情况。按Ctrl+D可退出Spark Shell

PS C:\Software\Spark\spark-2.4.5-bin-hadoop2.7\bin> ./spark-shell
Using Spark's default log4j profile: org/apache/spark/log4j-defaults.properties
Setting default log level to "WARN".
To adjust logging level use sc.setLogLevel(newLevel). For SparkR, use setLogLevel(newLevel).
Spark context Web UI available at http://DESKTOP-9LN67TS.mshome.net:4040
Spark context available as 'sc' (master = local[*], app id = local-1581394859054).
Spark session available as 'spark'.
Welcome to
    ____              __
    / __/__  ___ _____/ /__
    _\ \/ _ \/ _ `/ __/  '_/
/___/ .__/\_,_/_/ /_/\_\   version 2.4.5
    /_/

Using Scala version 2.11.12 (Java HotSpot(TM) 64-Bit Server VM, Java 1.8.0_241)
Type in expressions to have them evaluated.
Type :help for more information.

scala>

观察输出的内容，Spark Shell的Application UI开放在本地4040端口，可以访问看看，如下图所示。由于尚未运行任务，所以暂时没太多实质内容

IDEA

安装IDEA，安装Scala插件。这里主要解释如何创建一个方便本地测试的项目。

创建一个Scala项目，JDK版本选择1.8，Scala SDK版本选择2.11.12。创建完毕后，将Spark安装目录下的jars(即C:\Software\Spark\spark-2.4.5-bin-hadoop2.7\jars)设为项目依赖包。到目前为止，项目配置已完毕，可以直接在本地环境调试Spark项目。下面附上一段代码作为本地项目起点

import org.apache.spark.sql.SparkSession

object Application {

  def main(args: Array[String]): Unit = {
    val spark = SparkSession.builder().appName("LocalSparkApp").master("local[*]").getOrCreate()
    val sc = spark.sparkContext
    import spark.implicits._

    // val schema = "a INT, b STRING, c DOUBLE"
    // val df = spark.read.schema(schema).option("sep", "\t").csv("/local-path-to-file/")
    // df.createOrReplaceTempView("t")
    // spark.sql("select * from t where a > 10").show(20)

    // write your code here ...

    spark.close()
  }
}

对于我们面向生产的项目，JDK版本1.7，Scala版本2.10.7，依赖jar用生产环境的，然后编译出jar即可。

WSL / Linux

在纯Windows环境中，无法启动Spark Standalone模式集群，我们尝试从另外的角度解决这一问题。此处假定大家使用Windows10系统。如果是低版本Windows，那也许只能安装虚拟机Linux或者阿里云之类的云服务Linux来启动了。

启用WSL

在“控制面板”-“程序和功能”-“启用或关闭Windows功能”找到“适用于Windows的Linux子系统”并点击启用，如下图所示

或者在管理员权限启动的PowerShell中执行如下命令
1

Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux
然后重启计算机（界面勾选或者执行命令都需要重启）
安装一个Linux

打开Windows10应用商店(无需微软账户也可使用)，在搜索栏输入Ubuntu，建议选择Ubuntu 18.04 LTS安装。安装完成之后，在Windows开始菜单即可找到这一应用，点击打开。首次启动如下图所示，将会要求创建Unix用户名和密码，创建完毕即可正常使用(有时会卡在take a few minutes...一段时间，可以按一下回车。任何时候出现了问题都可以将这个Ubuntu应用卸载然后重新安装)

配置WSL

在我们安装的这个Ubuntu 18.04 LTS中，依次键入如下命令进行环境配置，不要粘贴一大段执行（尤其前几个sudo执行的命令），因为要输入刚刚设定的Unix密码

sudo apt update
sudo apt upgrade -y # 更新本地现已安装的软件包

sudo apt install openjdk-8-jdk -y # 安装JDK8

cd ~

# 本地盘会自动挂载到Linux子系统中，例如C盘挂载于 /mnt/c/，找到Windows系统的Spark，放到Linux中用
# 也可以将原来的tgz包重新解压到Linux系统某处，作为Linux自己的安装，如/opt/spark/
echo "export SPARK_HOME=/mnt/c/Software/Spark/spark-2.4.5-bin-hadoop2.7/" >> .profile 
echo 'export PATH=$PATH:$SPARK_HOME/bin' >> .profile
source .profile
ln -s /mnt/c/Software/Spark/spark-2.4.5-bin-hadoop2.7/sbin spark-sbin

cd spark-sbin
./start-master.sh # 启动Spark Master，此时可以查看localhost:8080查看Spark Master UI，从此处得到master url
./start-slave.sh spark://DESKTOP-9LN67TS.localdomain:7077 # 启动Spark Worker，刷新MasterUI，看到有了个Worker
cd ~
spark-shell --master spark://DESKTOP-9LN67TS.localdomain:7077   # 启动集群模式的Spark Shell，刷新MasterUI，看到有Application 出现

cd spark-sbin
./stop-slave.sh     # 停止Spark Master
./stop-master.sh    # 停止Spark Worker

# 不要用start-all.sh/stop-all.sh/start-slaves.sh/stop-slaves.sh，在WSL上，没有开启22端口，执行这几个命令会出错

WSL依然存在问题，比如最显著的IO性能问题、某些Linux应用尚不兼容问题(WSL2将着手解决)，但对我们而言，只是构造出一个开发测试环境，我认为这些问题可以不用在意，避免了安装虚拟机的各种麻烦，这点程度的损失是可以接受的。若是无法安装/配置WSL，而是有一个Linux机器，环境配置流程是一样的，按照安装JDK -> 安装Spark -> 启动Spark 的流程进行即可，几个主要Web UI如下所示：

Spark Master Web UI
Spark Worker Web UI
Spark Shell Web UI

至此，我们的已经配置启动了Standalone模式的Spark集群，之后可以向这个集群提交任务并运行。一般的提交命令如下所示：

`1`	`spark-submit --master spark://hostname:port --deploy-mode cluster --class xxx.spark.Application SparkApp.jar`

任务提交运行完毕后，Spark Master UI如下所示，可以通过界面上相应App的链接去查看之前任务运行的日志。

VSCode Remote

需要互联网连接

由于Windows上开发环境配置还是有些麻烦，测试环境/仅尝试下Spark的话，可以考虑使用Visual Studio Code进行远程开发(参考VS Code Remote Development)

Windows上安装好了VSCode后，在WSL/Linux上安装JDK + Spark + Maven即可开始。用到的VSCode插件有Remote WSL/Remote SSH和Scala(Metals)，这种方式的话，对于Windows环境将不再有任何要求

2. Scala Intro

Mon, 09 Mar 2020 00:00:00 +0800

Scala Intro

Scala是一门功能特别丰富的编程语言，我们涉及到的只是其一个较小的子集，此处列出相关文档，可以自行学习

Scala官方文档也提供了中文版，但有的翻译感觉还是有点生硬。此处将仅给出中文版的URL，如果要访问英文版，将URL中zh-cn去掉即可。

可以先看一下A Scala Tutorial for Java Programmers，这篇文档没有简体中文，有繁体中文版，但是很多概念跟我们说的名字不一样，要不直接看英文版得了。

官方提供了Tour of Scala系列文档来介绍语言的核心功能，这里列出这系列文档的子集，因为我们用到的也仅是个子集

基础: 最基本的语言基础，告诉我们表达式怎么写、函数怎么定义、类如何定义等
统一类型: 介绍了Scala类型层次结构
类: 定义一个类及其成员
元组: 需要了解是什么，怎么用
高阶函数: 好像有点厉害，只要能理解了函数可以作为参数和返回值即可
单例对象: 这个概念最好搞明白
泛型类: 泛型使用
类型推断: 由此，我们很多地方不需要写类型
包和导入: 跟java差不多

以上是我们用到的，搞懂以上概念，目前我们写的大部分代码看懂应该没什么问题，如果有时间还是建议把全系列翻一遍

Scala语法速查

3. 使用 Spark 进行数据分析

Mon, 09 Mar 2020 00:00:00 +0800

使用 Spark 进行数据分析

Spark简介
Spark处理数据
- Spark Core
- Spark SQL
开发一个Spark程序
开发常见问题

Spark简介

Apache Spark是个分布式计算框架，其提供了一大批高级API基于批处理或流式处理对大规模数据做ETL、机器学习和图处理等。可以用来开发Spark程序的编程语言有Scala、Python、Java、R和SQL。也可以将其理解成一个具备批处理和流处理能力的分布式数据处理引擎，支持SQL查询、图处理和机器学习等。Spark平台的组件间关系如下图所示：

Spark Core是整个Spark平台的核心部分，实现了重要的基础功能，例如输入输出、任务分发和调度、错误恢复等。Spark Core定义了一个特殊的数据结构RDD，并提供了一系列操作RDD的编程API。

Spark SQL是基于Spark API开发的能进行关系型数据处理的组件。该组件赋予Spark开发者对关系型数据处理的能力，也能让SQL用户能进行基于Spark的复杂分析。与Spark Core相比，Spark SQL是个从关系型视角对(半)结构化数据进行处理的框架，我们可以用SQL及SQL风格API来描述业务逻辑。

Spark Architecture

Spark程序可以看作是一组互相独立地跑在集群上的进程，这组进程接受driver进程(main所处的进程)中的SparkContext对象协调的。其简单结构如下图所示：

Cluster Manger负责为应用分配集群的资源，SparkContext适配了多种类型的集群（如Spark Standalone、Apache Mesos、Hadoop YARN、Kubernetes，我们实际情况是YARN）。Spark程序运行时，SparkContext首先去找Cluster Manager请求资源(executor，可以执行计算及存储应用数据的进程)，然后SparkContext将程序代码分发到各个executor，最后SparkContext把task发送到各个executor去执行。

需要指出以下事项：

每个Spark程序获得的是属于自己的executors，这些executors在整个程序运行过程中保持运行，以多线程方式处理任务。这个特点使多个Spark程序在调度侧（每个driver只调度自己的task）和执行侧（不同程序的task跑在不同的JVM里）都是互相隔离的。当然了，如果不把数据持久化到外部，那么不同的Spark程序也就无法共享数据。
Spark对于集群管理器并不关心，只关心自己要来的executor。
程序整个生命周期内，driver必须一直监听着executor发起的连接，这意味这driver和executors是必须网络通畅的。

`RDD`

RDD(即弹性分布式数据集)是Spark Core中的核心概念之一，是Spark最重要的数据抽象，所有数据处理都是基于对RDD的处理来实现。。从名字上体现出了其一些特点

弹性：这里的意思侧重“可恢复”，而不是“可伸缩”。RDD能从各种意外(比如节点挂掉、executor被误杀等)导致的数据丢失或损坏中进行重新计算，是支持错误恢复的
分布式：数据分布在集群的各个节点中
数据集：数据的集合，数据可以是简单的数值，也可以是更复杂的类型，例如Tuple、List、Map等数据结构，甚至可以是自行定义的类对象

除此之外，RDD有一些其他特点，这里列出几个

内存优先：Spark程序运行时，RDD中的数据会尽可能多且尽可能久地保存在内存中
不可变/只读：RDD一旦创建就不再可变，只能通过变换生成一个新的RDD
延迟计算：在一个action触发了任务实际运行之前，RDD中的数据尚不可及
可缓存：可以将RDD中全部数据持久化到某个存储，例如内存(默认及绝大多数情况)或者硬盘(由于硬盘存取速度问题，一般很少这么做)
并行化：对RDD数据的处理是并行的
类型化：RDD中的数据是有类型的，例如Long类型数据放在RDD[Long]中，Student对象放在RDD[Student]中

RDD支持两种类型的操作：transformation（转换）和action（动作）。从现有RDD生成新RDD的操作称为transformation，从RDD上运行执行计算然后求得一个值的操作称为action。transformation是延迟计算的。当对一个RDD执行了transformation之后，便构造出了一个“RDD血缘图”，记录了对RDD的变换操作和依赖信息。我们需要对依赖情况做到心里有数，宽窄依赖如下所示：

Resilient Distributed Datasets: A Fault-Tolerant Abstraction for In-Memory Cluster Computing

`Dataset[T]`&`DataFrame`

对于Spark SQL而言，Dataset[T]是其核心类之一，所有的操作都是对Dataset的处理(提交的SQL也会首先被解析成操作Dataset)。在内部，所有对Dataset的操作最终转换成RDD的操作。

Dataset是个分布式的数据集合。它是Spark1.6新增的接口，综合了RDD的优势(强类型，强大的λ函数能力)和Spark SQL的优化执行引擎优势。DataFrame是个数据已进行字段命名的Dataset。在Spark SQL中DataFrame=Dataset[Row]

对Dataset的操作也可以分transformation和action两类。其中变换操作(transformation)，分为“typed”和“untyped”两类。所谓“typed”，指的是编译时已知要处理的数据的类型(例如操作Dataset[Student])；相对应的，“untyped”指的是编译时不知道要处理的数据的类型（操作DataFrame）。

用Spark处理数据

对于有一些经验的同事，可以考虑深入研究Spark Core部分的算子，对比其使用场景；对于入门且马上要进行数据分析的同事，可以考虑直接使用Spark SQL，只需要一小部分的编程即可，数据分析可以直接以SQL实现。

另一方面，由于Spark Core与Spark SQL可以组合使用(基于Dataset/DataFrame/RDD的互相转换)，有经验的同事可以尝试各种操作，入门的话还是建议一步步来。

获取`SparkContext`&`SparkSession`对象

SparkContext是Spark服务的入口点，堪比Spark程序的心脏；SparkSession是Spark SQL的入口点。

构造/获取SparkContext对象的方式有很多，例如下面通过SparkConf来构造，但这种方式我用得不多了

1
2
3

import org.apache.spark.{SparkConf, SparkContext}
val conf = new SparkConf().setMaster("local[*]").setAppName("LocalSparkApp")
val sc = SparkContext.getOrCreate(conf)

开发应用程序时，一般以如下方式获取两者的对象。

import org.apache.spark.sql.SparkSession

// local spark application
val spark = SparkSession.builder().appName("LocalSparkApp").master("local[*]").getOrCreate()
// spark application
val spark = SparkSession.builder().appName("SparkApp").master("yarn").getOrCreate()
val sc = spark.sparkContext

建议：将SparkSession对象命名为spark、将SparkContext对象命名为sc，使之与Spark-Shell环境保持一致。这样核心逻辑代码可以直接拿到Spark-Shell中使用。

Spark-Shell会直接初始化这两者给我们使用(控制台输出的6-7行)。

PS C:\Software\Spark\spark-2.4.5-bin-hadoop2.7\bin> ./spark-shell
Using Spark's default log4j profile: org/apache/spark/log4j-defaults.properties
Setting default log level to "WARN".
To adjust logging level use sc.setLogLevel(newLevel). For SparkR, use setLogLevel(newLevel).
Spark context Web UI available at http://DESKTOP-9LN67TS.mshome.net:4040
Spark context available as 'sc' (master = local[*], app id = local-1581394859054).
Spark session available as 'spark'.
Welcome to
      ____              __
     / __/__  ___ _____/ /__
    _\ \/ _ \/ _ `/ __/  '_/
   /___/ .__/\_,_/_/ /_/\_\   version 2.4.5
      /_/

Using Scala version 2.11.12 (Java HotSpot(TM) 64-Bit Server VM, Java 1.8.0_241)
Type in expressions to have them evaluated.
Type :help for more information.

scala>

Spark Core

Spark Core程序始于SparkContext对象sc。RDD是Spark Core的核心类之一，所有数据处理都是基于对RDD的处理来实现。对其操作分为两类：transformation（转换）和action（动作）。transformation是生成新RDD的操作，例如map filter reduceByKey等，action是得出一个非RDD值的操作，比如count collect take saveAsTextFile等。

准备数据(构造RDD)

parallelize方法是从序列创建一个RDD，生产中一般不用，仅作学习和测试使用。

1
2

val rawStr = "Hello World!\naaa bbb ccc ddd\naaa aaa\nbbb\nccc\n"
val lineRdd = sc.parallelize(rawStr.lines.toSeq)

textFile方法是读取文本文件创建RDD，RDD中每个元素都是文件中的一行

`1`	`val fileRdd = sc.textFile("/path-to-file/")`

处理数据(操作RDD)

此处简单介绍下常见的算子，我们目前工作中常用的算子有map filter distinct reduceByKey join

map算子：将RDD中的每个元素转换成另一种状态，目标状态不设限

/* 
 * lineRdd  -> ["Hello World!", "aaa bbb ccc ddd", "aaa aaa", ...]
 * 
 * lowerRdd -> ["hello world!", "aaa bbb ccc ddd", "aaa aaa", ...]
 */
// val lowerRdd = lineRdd.map(line => line.toLowerCase())
val lowerRdd = lineRdd.map(_.toLowerCase)

flatMap算子：将RDD中的每个元素转换成一个可枚举的序列，然后将这些序列“压平”(也可以理解成连接起来)

/* 
 * lineRdd -> ["Hello World!", "aaa bbb ccc ddd", "aaa aaa", ...]
 * 
 * wordRdd -> ["Hello", "World!", "aaa", "bbb", ...]
 */
val wordRdd = lineRdd.flatMap(_.split(" "))

filter算子：检查每个元素，过滤掉不符合条件的元素

/* 
 * wordRdd     -> ["Hello", "World!", "aaa", "bbb", ...]
 * 
 * pureWordRdd -> ["aaa", "bbb", "ccc", "ddd", "aaa", ...]
 */
val pureWordRdd = wordRdd.filter(_.toCharArray.toSet.size == 1)

distinct算子：把数据集中的数据去重

/* 
 * pureWordRdd -> ["aaa", "bbb", "ccc", "ddd", "aaa", ...]
 * 
 * distinctRdd -> ["aaa", "bbb", "ccc", "ddd"]
 */
val distinctRdd = pureWordRdd.distinct()

count算子：统计RDD中数据的条数

`1`	`distinctRdd.count()`

take算子：从RDD中取指定数量的数据放到数组中

`1`	`distinctRdd.take(5).foreach(println)`

collect算子：将RDD中的所有数据收集到数组中（实际不太常用，除非能保证RDD中的数组足够少，能放到一个数组中去）

`1`	`distinctRdd.collect.foreach(println)`

groupBy算子：将RDD中的数据分组

/* 
 * pureWordRdd -> ["aaa", "bbb", "ccc", "ddd", "aaa", ...]
 * 
 * groupedRdd  -> ['a'->["aaa", "aaa",...], 'b'->["bbb",...], 'c'->["ccc"], ...]
 */
val groupedRdd = pureWordRdd.groupBy(_.charAt(0))

归纳类算子：reduce fold aggregate。这组算子的目标是将RDD归纳成一个值。下面演示其各自用法(功能目标一致，求RDD中字符串长度之和)

// def reduce(f: (T, T) => T): T
pureWordRdd.map(_.length).reduce(_ + _)
// def fold(zeroValue: T)(op: (T, T) => T): T
pureWordRdd.map(_.length).fold(0)(_ + _)
// def aggregate[U](zeroValue: U)(seqOp: (U, T) => U, combOp: (U, U) => U): U
pureWordRdd.aggregate(0)((i, s) => i + s.length, _ + _)

交并差算子：intersection union subtract。同数学上交集、并集、差集的概念

val rdd1 = sc.parallelize(Seq("A", "B", "C")) // [A, B, C]
val rdd2 = sc.parallelize(Seq("B", "C", "D")) // [B, C, D]
rdd1.intersection(rdd2) // rdd1 ∩  rdd2 = [B, C]
rdd1 ++ rdd2            // rdd1 ∪ rdd2 = [A, B, C, B, C, D]
rdd1.union(rdd2)        // rdd1 ∪ rdd2 = [A, B, C, B, C, D]
rdd1.subtract(rdd2)     // rdd1 -  rdd2 = [A]

以上算子是操作RDD[T]时常用的，当T是个二元组时，此时RDD[(K, V)]将会被隐式转换成PairRDDFunctions[K, V]对象，此时可以使用一些特殊算子，例如以下介绍的join系算子和xxxByKey系算子

归纳类算子：reduceByKey foldByKey aggregateByKey。下面演示其用法(统计各个Key的个数)

val rdd = sc.parallelize(Seq(("A", "AAA"), ("A", "aaa"), ("B", "bbb")))

// def reduceByKey(func: (V, V) => V): RDD[(K, V)]
rdd.map(t => (t._1, 1)).reduceByKey(_ + _)
// def foldByKey(zeroValue: V)(func: (V, V) => V): RDD[(K, V)]
rdd.map(t => (t._1, 1)).foldByKey(0)(_ + _)
// def aggregateByKey[U](zeroValue: U)(seqOp: (U, V) => U, combOp: (U, U) => U): RDD[(K, U)]
rdd.aggregateByKey(0)((i, _) => i + 1, _ + _)

groupByKey算子：该算子不再需要参数，行为与上述groupBy算子行为一致

关联类算子：join leftOuterJoin rightOuterJoin fullOuterJoin，主要区别在于对于关联失败数据的处理方式

val rdd1 = sc.parallelize(Seq(("A", "aaa"), ("B", "bbb"), ("C", "ccc")))
val rdd2 = sc.parallelize(Seq(("B", "BBB"), ("C", "CCC"), ("D", "DDD")))

rdd1.join(rdd2)             // [("B", ("bbb", "BBB")), ("C", ("ccc", "CCC"))]
rdd1.leftOuterJoin(rdd2)    // [("A", ("aaa", None)), ("B", ("bbb" ,Some("BBB"))), ("C", ("ccc",Some("CCC")))]
rdd1.rightOuterJoin(rdd2)   // [("B", (Some("bbb"), "BBB")), ("C", (Some("ccc"), "CCC")), ("D", (None, "DDD"))]
rdd1.fullOuterJoin(rdd2)    // [("A", (Some("aaa"), None)), ("B", (Some("bbb"), Some("BBB"))), ("C", (Some(ccc), Some("CCC"))), ("D", (None, Some("DDD")))]

以上算子便是离线数据分析常用的算子，对于数据进行的分析都是基于这些算子的组合使用，常用才能熟悉。关于以上列出算子的官方文档，请参考ScalaDoc：RDD，PairRDDFunctions

保存数据(保存RDD)

对于结果数据保存，我们常用的是saveAsTextFile方法，在调用此方法之前，需要保证数据已经是\t分隔字段的单行字符串形式，一般需要用map算子转换一下数据的形式，如下所示：

`1`	`rdd.map(_.mkString("\t")).saveAsTextFile("/path-to-result/")`

Spark SQL

此处介绍Spark SQL主要为了降低数据处理的门槛，基于我们已经很熟悉的SQL语言，马上就能进行基本的数据处理工作。因此侧重以SQL方式进行数据处理，对DatasetAPI细节介绍较少，若要以编程方式使用，可参考其文档ScalaDoc - Dataset

同样的逻辑，使用DatasetAPI和SQL表达在性能上没有任何差别。

首先给出一段简单代码，用以揭示使用Spark SQL进行数据分析的一般流程

// --------------- preparing ---------------
// construct schema
val schema = new StructType()
  .add("id", DataTypes.LongType, nullable = true)
  .add("name", DataTypes.StringType, nullable = true)
  .add("age", DataTypes.IntegerType, nullable = true)
  .add("score", DataTypes.DoubleType, nullable = true)

// load file, create dataframe
val df = spark.read
  .schema(schema)
  .option("header", false)      // default is false
  .option("inferSchema", false) // default is false
  .option("sep", "\t")
  .csv("/path-to-bcp-file/")

// register as a temp view/table
df.createOrReplaceTempView("tableName")

// --------------- processing ---------------
// execute sql statement
val result = spark.sql("select * from tableName where name is not null and age > 18 and score > 60")

// --------------- saving ---------------
result.write.option("sep", "\t").csv("/path-to-result-dir/")

// --------------- exit ---------------
spark.close()

我们主要对数据准备、处理、保存阶段进行详细的讨论。

Preparing

数据准备阶段的工作是告知Spark SQL：我们的数据是什么结构，怎么样能拿到。解答这两个问题的办法有很多，我们视情况选择自己用得顺手的即可。此处给出两类办法以供参考。

定义业务数据类型

// define class
case class Student(id: String, name: String, age: Int, score: Double)

// read file
val ds = sc.textFile("/path-to-file/")                          // type: RDD[String]  sample: "001,tom,18,60.0"
  .map(_.split(","))                                            // type: RDD[Array]   sample: ["001","tom","18","60.0"]
  .map(arr => (arr(0), arr(1), arr(2).toInt, arr(3).toDouble))  // type: RDD[Tuple]   sample: ("001","tom",18,60.0)
  .map(t => Student(t._1, t._2, t._3, t._4))                    // type: RDD[Student] sample: Student("001","tom",18,60.0)
  .toDS()                                                       // type: Dataset[Student]

// register as a temp view/table
ds.createOrReplaceTempView("tableName")

分析以上代码，首先定义了一个Student类型，我们读取进来的数据要转换成此类型的一组实例。然后我们用Spark Core的map算子进行数据格式的转换，转换成了一批Student对象放在了RDD中，最后转换成Dataset[Student]类型。此时，Spark SQL的两个问题回答完毕：要操作的数据Student(字段名称和字段类型已知)，要操作的数据从上游RDD直接可取。我们将这个Dataset[Student]类型的对象注册到Spark SQL系统供下面的代码使用

注1：Student类的定义不能放到方法体里

注2：要调用toDS方法，需要在调用前(一般在SparkSession的对象spark构造完毕后)导入一些隐式成员，即加上以下语句import spark.implicits._

构造Schema

Spark SQL使用Schema对数据的结构进行描述，Schema包含列名、数据类型、是否可空。我们可以直接构造出一个Schema告知Spark SQL我们的数据是什么结构。

// construct schema
val schema = new StructType()
  .add("id", DataTypes.LongType)
  .add("name", DataTypes.StringType)
  .add("age", DataTypes.IntegerType)
  .add("score", DataTypes.DoubleType)

// read file
val rdd = sc.textFile("/path-to-file/")                         // type: RDD[String]  sample: "001,tom,18,60.0"
  .map(_.split(","))                                            // type: RDD[Array]   sample: ["001","tom","18","60.0"]
  .map(arr => (arr(0), arr(1), arr(2).toInt, arr(3).toDouble))  // type: RDD[Tuple]   sample: ("001","tom",18,60.0)
  .map(Row.fromSeq(_))                                          // type: RDD[Row]

val df = spark.createDataFrame(rdd, schema)

// register as a temp view/table
df.createOrReplaceTempView("tableName")

分析以上代码，我们首先构造了一个StuctType对象来描述数据结构，然后读取文件，与上面不同的是，最终转换成RDD[Row]类型，然后调用createDataFrame方法。createDataFrame方法的两个参数一个回答了数据来源的问题，另一个回答了数据结构的问题。

注1：文件加载部分可以进行简化

1
2

val df = spark.read.schema(schema).option("sep", "\t").csv("/path-to-bcp-file/")
df.createOrReplaceTempView("tableName")

使用了Spark SQL内置的一些工具进行简化。schema方法指定了要加载的数据的结构，csv方法指出了数据文件的格式，我们通过option方法指定一些选项(此处指定了分隔符以适配bcp文件)。加载选项的详细列表请参考ScalaDoc - DataFrameReader

注2：构造Schema部分可以进行简化

其实DataFrameReader已有类似API，即spark.schema("id LONG, name STRING, ...").option(...)...，其中schema方法接受Schema字符串并自动转换，但这个API是Spark 2.3.0新增，内部平台版本应该是2.1.x，还没有此API

鉴于此，我们可以实现一个SchemaInterpolator使之更易用，最终效果如下所示：

1
2

import SchemaInterpolator._
val schema = schema"id long, name string, age int, score double"

SchemaInterpolator的简易实现已附在本文档

注3：自描述数据源

有些数据源能描述自己的数据结构，例如jdbc json csv parquet等，这种情况我们也可以让Spark SQL自行推断数据结构，以csv文件为例

val df = spark.read
  .option("header", true)
  .option("inferSchema", true)
  .csv("/path-to-bcp-file/")
df.createOrReplaceTempView("tableName")

Processing

准备阶段已经将临时视图注册到了Spark SQL系统中，我们可以直接提交要处理的SQL。此处仅给出一些样例，旨在揭示Spark SQL的各种可能，一般我们能想到的操作，都是可以做到的

spark.sql(sqlText)的执行结果是DataFrame(即Dataset[Row])，可以将结果保存、注册为新视图、替换之前的视图等

val df = ... 
// create view 
df.createOrReplaceTempView("t1")

val df1 = spark.sql("select * from t1 where t1.xxx is not null and ...")
// replace view 
df1.createOrReplaceTempView("t1")

这段代码执行完毕之后，“t1"已经变成了筛选之后的数据，直接用就可以，因此，无需总是为给表取名字挠头

多数据集join是可以的，sql直接能做

import org.apache.spark.sql._
import org.apache.spark.sql.types._

import spark.implicits._ 

val schema = new StructType().add("k", DataTypes.StringType).add("v", DataTypes.StringType)

val rdd1 = sc.parallelize(Seq(("A", "aaa"), ("B", "bbb"), ("C", "ccc"))).map(Row.fromTuple(_))
val rdd2 = sc.parallelize(Seq(("B", "BBB"), ("C", "CCC"), ("D", "DDD"))).map(Row.fromTuple(_))

spark.createDataFrame(rdd1, schema).createOrReplaceTempView("t1")
spark.createDataFrame(rdd2, schema).createOrReplaceTempView("t2")

val df = spark.sql("select t1.k as k, t1.v as v1, t2.v as v2 from t1 join t2 on t1.k = t2.k")

更多JOIN操作请参考：LanguageManual Joins

Spark SQL内置函数和运算符

Spark SQL提供了一批函数和运算符，我们可以直接在SQL里面使用，下面给出两个例子

例子1：过滤掉某字段的字符串长度小于10的数据

`1`	`select * from t1 where length(t1.filed0) >= 10`

例子2：根据出生日期，算出年龄

`1`	`select *, int(date_format(now(), 'yyyy')) - int(year(t.birth)) as age from t`

Spark SQL的内置函数列表请参考：Spark SQL, Built-in Functions

UDF(用户自定义函数)

思考前面的例子2，根据出生日期计算年龄，用代码写我们有无数种实现方式，但是只用内置函数，好像很麻烦，所以我们实现个UDF，如下所示

// define an normal function
val calcAge: String => Int = (birth: String) => {
  import java.text.SimpleDateFormat
  import java.util.Date

  val now = new Date()
  val fmt = new SimpleDateFormat("yyyy")
  val thisYear = fmt.format(now).toInt
  val birthYear = birth.substring(0, 4).toInt
  thisYear - birthYear
}
// register udf
spark.udf.register("calcAge", calcAge)
// use it!
spark.sql("select *, calcAge(t.birth) as age from t")

分析以上代码，流程很清晰，写个普通函数 -> 注册到Spark SQL -> 直接在SQL中使用。

注意：尽量不要用这种方式！UDF对Spark SQL来说就是个黑盒，它无法对此做出优化，复杂UDF很有可能造成性能瓶颈。除非别无选择，否则不要用UDF

一些有用的文档

Spark SQL与Apache Hive的兼容性：Compatibility with Apache Hive

Hive语言手册(我们主要关注SQL部分)：LanguageManual

SELECT：LanguageManual Select

Saving

数据保存的做法依然有很多，考虑到我们的实际需求，此处只推荐一种做法，如下所示

1
2

val df = spark.sql("select field1, field2, ... from t")
df.write.option("sep", "\t").csv("/path-to-result-dir/")

实际进行保存之前，建议执行一次筛选操作，用以确认要保存的字段并且保证字段的顺序，然后执行保存。

更多数据保存的相关选项，请参考ScalaDoc - DataFrameWriter

`SchemaInterpolator`

一个基于StringInterpolator的SchemaInterpolator实现

object SchemaInterpolator {

  import scala.util.{Try, Failure, Success}
  import org.apache.spark.sql.types._

  implicit class SparkSQLSchema(val sc: StringContext) {

    // InnerStructField -> index option, field
    private type InnerStructField = (Option[Int], StructField)

    // val schema = schema"a int, b string false, c double true some-comment"
    // val schema = schema"0 a int, 2 c double true, 3 d string"
    def schema(args: Any*): StructType = {
      val str = sc.s(args: _*).trim
      if (str.isEmpty) throw new IllegalArgumentException("Empty Schema String")

      val innerSeq = str split "," map parseInnerStructField
      innerSeq.head match {
        case (None, _) => StructType(innerSeq.map(_._2))
        case (Some(_), _) =>
          val i2f = innerSeq.map({ case (oi, f) => (oi.get, f) }).toMap
          val fSeq = (0 to i2f.keys.max).map(i => i2f.getOrElse(i, StructField(s"fake_name_$i", StringType)))
          StructType(fSeq)
      }
    }

    private def parseInnerStructField(str: String): InnerStructField = {
      assert(str != null && !str.trim.isEmpty, "this is an empty string!")
      val seq = str.trim.split("\\s+").toSeq
      Try(seq.head.toInt) match {
        case Success(index) => (Some(index), parseStructField(seq.tail))
        case Failure(_) => (None, parseStructField(seq))
      }
    }

    private def parseStructField(seq: Seq[String]): StructField = {
      seq match {
        case name +: typeStr +: Nil =>
          StructField(name, typeStr)
        case name +: typeStr +: nullable +: Nil if Try(nullable.toBoolean).isSuccess =>
          StructField(name, typeStr, nullable.toBoolean)
        case name +: typeStr +: nullable +: tail if Try(nullable.toBoolean).isSuccess =>
          StructField(name, typeStr, nullable.toBoolean).withComment(tail.mkString(" "))
        case name +: typeStr +: tail =>
          StructField(name, typeStr).withComment(tail.mkString(" "))
        case _ => throw new IllegalArgumentException(s"not a valid struct field: '${seq.mkString(" ")}'")
      }
    }

    private implicit def typeStrToDataType(str: String): DataType = {
      str match {
        case "bool" | "boolean" | "Boolean" => DataTypes.BooleanType
        case "byte" | "Byte" => DataTypes.ByteType
        case "short" | "Short" => DataTypes.ShortType
        case "int" | "integer" | "Integer" => DataTypes.IntegerType
        case "long" | "Long" => DataTypes.LongType
        case "float" | "Float" => DataTypes.FloatType
        case "double" | "Double" => DataTypes.DoubleType
        case "decimal" | "bigdecimal" | "BigDecimal" => DataTypes.createDecimalType()
        case "string" | "String" => DataTypes.StringType
        case "timestamp" | "TimeStamp" => DataTypes.TimestampType
        case "calendarinterval" | "CalendarInterval" => DataTypes.CalendarIntervalType
        case "date" | "Date" => DataTypes.DateType
        case "null" | "Null" => DataTypes.NullType
        case "byte[]" | "Byte[]" | "Array[Byte]" => DataTypes.BinaryType
        case _ if str.endsWith("[]") => DataTypes.createArrayType(str.substring(0, str.length-2))
        case _ if str.matches("^Array\\[\\S+\\]$") => DataTypes.createArrayType(str.substring(6, str.length-1))
        // never hit this case, because type string was splited by ',' above
        case _ if str.matches("^Map\\[\\S+,\\S+\\]$") || str.matches("^Map<\\S+,\\S+>$") =>
          val i = str.indexOf(',')
          val kt = str.substring(4, i)
          val vt = str.substring(i+1, str.length-1)
          DataTypes.createMapType(kt, vt)
        case _ => throw new IllegalArgumentException(s"cannot resolve the type: '$str'!!!!")
      }
    }
  }
}

开发一个Spark程序

参考环境准备中IDEA小节创建项目，然后将起始代码复制进去

注意构造SparkSession对象时master()方法接受的参数：如果是要在本地运行，使用"local[*]"；如果是链接Spark Standalone集群调试，使用形如"spark://hostname:port"的Spark Master URL（可以在Spark Master Web UI找到）；如果是要打成jar包放到公司的平台上跑，使用"yarn"参数

选用自己使用顺手的组件进行功能实现和测试，一般现在本地环境以样例数据测试核心逻辑。然后按照部署目标的要求进行打包，部署到实际环境中进行测试。应当注意运行效率方面，有时候还需要进一步优化。

开发常见问题

这里列出几个开发的时候比较常见的问题，此处列出的代码仅供演示，可能不完全正确

数据过滤不严谨

这种情况出现还算比较多，实际处理数据时应认真思考，尽可能筛掉异常数据

case class Student(id: String, name: String, age: Int)

val students = sc.textFile("/path/student-info.nb")
  .map(_.split("\t"))
  .map(a => (a(0), a(1), a(2)))   // 可能出现数组越界异常
  .map(t => Student(t._1, t._2, t._3.toInt))  // 可能出现转换失败异常

// 可以采用以下方式解决

val students = sc.textFile("/path/student-info.nb")
  .map(_.split("\t"))
  .filter(_.length == 3)    // 保证数组长度，消除数组越界异常
  .map(a => (a(0), a(1), a(2)))
  .filter(t => Try(t._3.toInt).isSuccess)   // 保证字段能正常转换
  .map(t => Student(t._1, t._2, t._3.toInt))

以上演示了从数据格式上进行异常数据筛选，但某些数据从业务上也是不合法的，因此后续可能需要更多的filer和map进行数据筛选和变换

过多数据放到一个集合/节点

这种情况一般发生于使用Spark Shell进行快速数据分析时发生

rdd.collect().foreach(println)  // collect算子把rdd中的全部数据放到一个数组了，很容易就会挂掉，这需要我们自行保证rdd中的数据不多

// 可以先统计下数量，如果发现不多，那么可以这么做
rdd.count()

// 也可以使用take
rdd.take(20).foreach(println)

使用外部变量

先看一个反例

val names = new java.util.HashSet[String]()
nameRdd.foreach(n => names.Add(n))    // 使用foreach进行结果整理
someRdd.map(x => {names.Add(x.name); x.other})  // map过程中“顺便”干点别的

// 或者这样
var sum = 0
intRdd.foreach(i => sum += i)

基于我们熟悉的面向对象编程，已经养成了这么一个习惯：遍历一个集合，在遍历过程中提取我们需要的信息放到之前定义的变量里。

在普通单线程Scala程序中，这么做虽然不推荐，但还是正确的；但是在Spark程序中，对RDD的操作如果这么干，是不正确的。要注意我们之前对RDD的并行化特点的介绍，Spark会把我们用λ表达的逻辑及其捕获的自由变量打包分发到每个节点，每个节点上的names sum与driver程序上的不再有任何关系，各节点的子任务运行完毕后，对变量的修改也不会反映到我们期望的变量身上，所以最终得到了错误的结果。

这类问题没什么统一的解决方案，只能是具体问题具体看，算是在强制我们熟悉一下函数式编程。

以上反例，可以这么改

val names = nameRdd.distinct.collect    // 用distinct算子去重 当然也得保证name数量没有太多

// map中不要“顺便”做任何事情了，逻辑分离开单独处理就好

val sum = intRdd.reduce(_ + _)  // 用reduce算子求和

4. 实际开发的注意事项

Mon, 09 Mar 2020 00:00:00 +0800

实际开发的注意事项

自研平台
- 版本
- 认证及资源隔离
- 项目部署
华为
- 版本
- 认证及资源隔离
- 项目部署
阿里云
浪潮

公司平台

1. 版本问题

NS平台基础JDK是1.7 Scala版本2.10.x Spark版本2.1.x 开发时应注意API版本

Spark API应该还好，就我们目前的使用和开发方式，一般不太会撞上恰好2.1.x没有该API的情况，若要保证正常，可以下载spark-2.1.3-bin-hadoop2.6作为测试环境（感觉意义不大，因为Scala版本还是高于平台）

注意对于Scala 和 Java的使用，需要换成适配版本进行开发和打包

2. 认证及资源分离问题

在公司平台上启动任务需要注意指定用户、指定队列

`1`	`spark-shell --master yarn --principal xxx --keytab xxx.keytab --queue xxx`

3. 项目部署

oozie被包装得妈都不认识了，得参考任务调度服务的开发文档。

华为平台

华为平台是堡垒机操作，似乎防火墙只允许有限的几个机器访问运维界面(或者是因为集群在自己的子网中，在集群外根本找不到目标机器)，因此比较强烈依赖命令行操作

操作华为集群要先加载环境（类似这样的命令）

`1`	`source bigdata-env`

有时候环境中的用户身份还不具有操作集群的权限，还需要换个身份

`1`	`kinit -kt xxx.keytab xxx # ???`

1. 版本

印象中华为平台的基础JDK是1.8，Scala版本应该也不是2.10.x这么低，版本问题在华为集群上应该并不严重。印象中不知从哪听了一耳朵，有些地方华为的集群已经是Hadoop3.x，有些应用还需适配

2. 认证及资源分离

华为集群对于动手启动的Spark Shell没有启用dynamic executor，因此启动一般分配有限的几个executor，任务没什么好并行的当然跑的慢了，所以要记得手动指定executor个数，如下所示

注意：手动指定的executor个数必须是基于数据总量和具体任务进行考量，还应当看一下集群当前的状况，是不是资源特别紧张。不能武断地直接指定几百个executor跑自己的事情

`1`	`spark-shell --master yarn --num-executors 32`

3. 部署

我记得是HUE界面上拖出来的进行部署的，也可以直接使用oozie进行定时/周期任务部署。华为集群上任务部署跟业界普遍做法比较一致，华为对这块没有进行特别深入的定制和包装

阿里云

尚未交过学费，似乎变动炒鸡大，貌似只有一个点是这个平台

浪潮

还没亲眼见过，听说直接就是原生的一套跑着

5. 小测试

Mon, 09 Mar 2020 00:00:00 +0800

练手

以下各个问题基于最后附的数据，可以同时尝试下用SQL和RDD API来解决问题。

配置环境，把本地Spark Shell跑起来

能跑起来Spark Shell，说明环境配置正常。这是最基本的前提，可以使用IDEA直接进行本地调试
过滤掉所有不正常数据
按总成绩排名从高到底输出学号和姓名
找出有不及格科目的同学
分别找出各个科目的第一名
分别找出男生和女生的第一名

提供了几个解决思路，但是建议不要马上就看

数据

将数据保存到本地，做成bcp文件

各个字段分别是：学号，姓名，语文，数学，英语

id-1	学生-1	43	30	0
id-2	学生-2	76	83	77
id-3	学生-3	98.5	76	90
id-4	学生-4	100	79	96
id-5	学生-5	59	85	76
id-6	学生-6	69	78	83
id-7	学生-7	75	88	69
id-8	学生-8	94	abc	79
id-9	学生-9		82	91
id-10	学生-10	87	68	85
id-11		84	56	95
	学生-12	99	79	60

字段是：学号，性别

id-1	男
id-2	女
id-3	男
id-4	女
id-5	男
id-6	女
id-7	男
id-8	女
id-9	男
id-10	女
id-11	
	女

6. 小测试参考思路

Mon, 09 Mar 2020 00:00:00 +0800

几个解答思路

提供几个思路以解答前面提出的问题。

其中理解门槛最低的是Spark SQL版，用SQL来描述业务逻辑，应该还是比较友好的。

两个Spark Core版本的解决方案没有这么直观，两者都需要开发者熟悉常用算子。此外，使用基本数据结构的版本，需要把数据结构的变换过程理解吃透；定义业务类的版本理解稍容易些，搞清楚Scala中object、class、case class的概念应该就可以了。

1. Spark SQL

import org.apache.spark.sql.SparkSession

object Application {
  def main(args : Array[String]) {
    val spark = SparkSession.builder().appName("SparkApp").master("local[*]").getOrCreate()
    import spark.implicits._

    val scorebcp = "/mnt/c/Users/mxtao/Desktop/score.nb"
    val genderbcp = "/mnt/c/Users/mxtao/Desktop/gender.nb"

    // 加载数据
    val scoreSchema = "id string, name string, yw float, sx float, yy float"
    spark.read.option("sep", "\t").schema(scoreSchema).csv(scorebcp).createOrReplaceTempView("score")
    val genderSchema = "id string, gender string"
    spark.read.option("sep", "\t").schema(genderSchema).csv(genderbcp).createOrReplaceTempView("gender")

    // 过滤无效数据，顺便求了总成绩放在这
    spark.sql("select *, (yw + sx + yy) as total from score where id is not null and name is not null and yw is not null and sx is not null and yy is not null").createOrReplaceTempView("score")
    spark.sql("select * from gender where id is not null and gender is not null").createOrReplaceTempView("gender")

    // 按总成绩排名从高到底输出学号和姓名
    spark.sql("select id, name, total from score order by total desc").show()
    // 找出有不及格科目的同学
    spark.sql("select * from score where yw < 60 or sx < 60 or yy < 60").show()
    // 分别找出各个科目的第一名
    spark.sql("select * from score order by yw desc limit 1").show()
    spark.sql("select * from score order by sx desc limit 1").show()
    spark.sql("select * from score order by yy desc limit 1").show()
    // 分别找出男生和女生的第一名
    spark.sql("select s.id, s.name, g.gender, s.total from score s join gender g on s.id == g.id").createOrReplaceTempView("gscore")  // 其实也可以不创建临时表，直接作为子查询也可
    spark.sql("select * from gscore where gender == '男' order by total desc limit 1").show()
    spark.sql("select * from gscore where gender == '女' order by total desc limit 1").show()

    spark.stop()
  }
}

2. Spark Core + 定义业务类

import org.apache.spark.sql.SparkSession
import scala.util.Try

// ----------- 定义业务类 ------------
object StudentScore {
  // 尝试从字符串构造业务对象
  def tryApply(str: String): Option[StudentScore] = {
    if (verify(str))
      Some(StudentScore(str))
    else
      None
  }

  // 重载一个apply方法
  def apply(str: String): StudentScore = {
    // require(verify(str), "not a correct string!")
    val arr = str.split("\t")
    StudentScore(arr(0), arr(1), arr(2).toFloat, arr(3).toFloat, arr(4).toFloat)
  }

  // 验证外部输入的字符串或者数组是否合法
  def verify(str: String): Boolean = str!=null && str.nonEmpty && verify(str.split("\t"))
  def verify(arr: Array[String]): Boolean = arr!=null && arr.length==5 && arr.forall(_.nonEmpty) && arr.slice(2, 5).forall(s => Try(s.toFloat).isSuccess)
}
// 注意，这里是一个 case class，要理解清楚它与普通 class 有何不同
case class StudentScore(val id: String, val name: String, val yw: Float, val sx: Float, val yy: Float){
  def total: Float = yw + sx + yy
  def isPassed: Boolean = yw >= 60.0 && sx >= 60.0 && yy >= 60.0
  def notPassed: Boolean = !isPassed
}

// ----------- 主程序本体 --------------
object Application {
  def main(args : Array[String]) {
    val spark = SparkSession.builder().appName("SparkApp").master("local[*]").getOrCreate()
    val sc = spark.sparkContext
    import spark.implicits._

    val scorebcp = "/mnt/c/Users/mxtao/Desktop/score.nb"
    val genderbcp = "/mnt/c/Users/mxtao/Desktop/gender.nb"

    val score = sc.textFile(scorebcp)
      .map(s => StudentScore.tryApply(s))   // 尝试从字符串构造对象
      .filter(_.nonEmpty)                   // 把构造失败的过滤掉
      .map(_.get)                           // 取得对象本体，此时得到RDD[StudentScore]
    // 也可以用另一种处理办法
    // val score = sc.textFile(scorebcp)
    //   .filter(s => StudentScore.verify(s))   // 验证字符串是否正确，把不正确的字符串丢掉
    //   .map(s => StudentScore(s))             // 从字符串构造业务对象
    val gender = sc.textFile(genderbcp)
      .map(_.split("\t"))
      .filter(_.length == 2)
      .map(a => (a(0), a(1)))
      .filter(t => t._1.nonEmpty && t._2.nonEmpty)
    
    // 按总成绩排名从高到底输出学号和姓名
    score.sortBy(_.total, ascending = false)
      .map(s => s"${s.id}\t${s.name}")
      .collect()
      .foreach(println)

    // 找出有不及格科目的同学
    score.filter(_.notPassed).collect.foreach(println)
    
    // 分别找出各个科目的第一名
    score.sortBy(_.yw, ascending = false).take(1).foreach(print)
    score.sortBy(_.sx, ascending = false).take(1).foreach(print)
    score.sortBy(_.yy, ascending = false).take(1).foreach(print)

    // 分别找出男生和女生的第一名
    val score2 = score.map(s => (s.id, s)).join(gender).map(_._2)
    score2.filter(_._2 == "男").map(_._1).sortBy(_.total, ascending = false).take(1).foreach(println)
    score2.filter(_._2 == "女").map(_._1).sortBy(_.total, ascending = false).take(1).foreach(println)

    spark.close()
  }
}

3. Spark Core + 基本数据结构

import org.apache.spark.sql.SparkSession
import scala.util.Try

object Application {
  
  def main(args : Array[String]) {
    val spark = SparkSession.builder().appName("SparkApp").master("local[*]").getOrCreate()
    val sc = spark.sparkContext
    import spark.implicits._

    val scorebcp = "/mnt/c/Users/mxtao/Desktop/score.nb"
    val genderbcp = "/mnt/c/Users/mxtao/Desktop/gender.nb"

    // 读取文件，过滤无效数据
    val score = sc.textFile(scorebcp)
      .map(_.split("\t"))
      .filter(_.length == 5)    // 过滤掉字段有缺失的数据
      .map(a => (a(0), a(1), a(2), a(3), a(4)))     // 把数组转换成元组
      .filter(t => t._1.nonEmpty && t._2.nonEmpty && t._3.nonEmpty && t._4.nonEmpty && t._5.nonEmpty)           // 保证必要字段不为空
      .filter(t => Try(t._3.toFloat).isSuccess && Try(t._4.toFloat).isSuccess && Try(t._5.toFloat).isSuccess)   // 保证成绩字段是合法的
      .map(t => (t._1, t._2, t._3.toFloat, t._4.toFloat, t._5.toFloat))     // 转换成 (学号, 姓名, 语文, 数学, 英语) 形式
    val gender = sc.textFile(genderbcp)
      .map(_.split("\t"))
      .filter(_.length == 2)
      .map(a => (a(0), a(1)))
      .filter(t => t._1.nonEmpty && t._2.nonEmpty)
    
    // 按总成绩排名从高到底输出学号和姓名
    score.map(t => (t._1, t._2, t._3 + t._4 + t._5))    // 转换成 (学号, 姓名, 总成绩) 形式
      .sortBy(_._3, ascending = false)                  // 以总成绩为key，按从低到高排序
      .map(t => s"${t._1}\t${t._2}")                    // 格式化数据，为输出做准备
      .collect()                                        // 将分布在各个节点的数据拿到本地
      .foreach(println)                                 // 打印到控制台

    // 找出有不及格科目的同学
    score.filter(t => t._3 < 60.0 || t._4 < 60.0 || t._5 < 60.0)
      .collect()
      .foreach(println)
    
    // 分别找出各个科目的第一名
    score.sortBy(_._3, ascending = false)
      .take(1)
      .foreach(println)
    score.sortBy(_._4, ascending = false)
      .take(1)
      .foreach(println)
    score.sortBy(_._5, ascending = false)
      .take(1)
      .foreach(println)

    // 分别找出男生和女生的第一名
    val score2 = score.map(t => (t._1, (t._1, t._2, t._3 + t._4 + t._5)))   // 转换成二元组，为join做准备，此处转换成了 (学号, (学号, 姓名, 总成绩)) 形式
      .join(gender)     // 与gender数据集(结构为：(学号,性别))关联碰撞，策略为丢弃所有未关联数据，结果结构为: (学号, ((学号, 姓名, 总成绩), 性别))
      .map(_._2)        // 丢掉不再使用的key，然后结构变为：((学号, 姓名, 总成绩), 性别)
    score2.filter(_._2 == "男")
      .map(_._1)
      .sortBy(_._3, ascending = false)
      .take(1)
      .foreach(println)
    score2.filter(_._2 == "女")
      .map(_._1)
      .sortBy(_._3, ascending = false)
      .take(1)
      .foreach(println)

    spark.close()
  }
}

Spark开发入门-介绍

Mon, 09 Mar 2020 00:00:00 +0800

spark-dev-tour

Spark Application Development Tour

大纲

下方链接可能失效，可尝试系列目录

培训附件

环境准备
- Windows
  - JDK
  - Scala SDK
  - Spark
  - IDEA
- WSL / Linux
  - VSCode Remote
Scala Language

Scala编程语言入门
Spark开发
- Spark简介
- Spark处理数据
  - Spark Core
  - Spark SQL
- 开发一个Spark程序
- 开发常见问题
实际开发的注意事项

主要公司自研平台和华为的平台
练手

几个练习

Spark Release 3.0.0

Scala on boboboker~

泛型

泛型

基本语法

C#

泛型接口、泛型类和泛型方法

泛型委托和泛型事件

泛型数组

F#

Java

泛型约束

C#

泛型约束常规应用

default约束

关于?标注

关于歧义

消除歧义

unmanaged约束

委托约束

枚举约束

类型参数继承/实现声明的类/接口(F-Bound)

allows ref struct约束

F-Bound

可变性

C#

泛型接口/委托中的可变性

非泛型场景中的可变性

高阶泛型

Higher Kind

Higher Rank

参考链接

Scala Style

Scala Style

缩进和换行

命名约定

类、特质

对象

包

方法

Accessors/Mutators 属性访问器、修改器

无参方法/函数的括号

符号方法名

常量、值、变量和方法

类型参数（泛型）

HKT

注解

特别说明

类型

类型推断

类型注解

Type ascription / 类型归属？

函数

结构类型

嵌套代码块

代码块

括号

声明

类

类中各元素的顺序

方法

过程式语法

方法修饰符

方法体

多参数列表

高阶函数

字段

函数值

控制结构

花括号

for-Comprehensions

细碎的条件判断

方法调用

0元函数/无参函数

Postfix Notation/后缀写法

1元函数/单个参数 - 中缀写法

符号方法、操作符

高阶函数

文件

多元素文件

文档

`default`约束

关于`?`标注

`unmanaged`约束

`allows ref struct`约束

`for`-Comprehensions

`RDD`

`Dataset[T]`&`DataFrame`

获取`SparkContext`&`SparkSession`对象

`SchemaInterpolator`